Blame


1 057c47a3 2021-07-18 op # Telescope
2 057c47a3 2021-07-18 op
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.
5 4def0885 2021-03-12 op
6 62dba329 2021-08-18 op Features:
7 62dba329 2021-08-18 op
8 62dba329 2021-08-18 op - tabs
9 62dba329 2021-08-18 op - bookmarks
10 62dba329 2021-08-18 op - privsep
11 62dba329 2021-08-18 op - minibuffer live narrowing
12 ba06b646 2021-08-28 op - multiple protocols support
13 ba06b646 2021-08-28 op - fully customizable
14 62dba329 2021-08-18 op
15 4def0885 2021-03-12 op There are still various things missing or, if you prefer, various
16 4def0885 2021-03-12 op things that you can help develop :)
17 4def0885 2021-03-12 op
18 4def0885 2021-03-12 op - subscriptions
19 3be78a24 2021-03-17 op - tofu oob verification
20 4def0885 2021-03-12 op - client certificates
21 0f7e6318 2021-06-20 op - add other GUIs: at the moment it uses only ncurses, but telescope
22 0f7e6318 2021-06-20 op shouldn't be restricted to TTYs only!
23 4def0885 2021-03-12 op
24 cd2f2c82 2021-07-24 op [![asciicast](https://asciinema.org/a/426862.svg)](https://asciinema.org/a/426862)
25 4def0885 2021-03-12 op
26 2058a15d 2021-03-13 op
27 cd302034 2021-03-15 op ## Why yet another browser?
28 cd302034 2021-03-15 op
29 cd302034 2021-03-15 op One of the great virtues of Gemini is its simplicity. It means that
30 cd302034 2021-03-15 op writing browsers or server is easy and thus a plethora of those
31 cd302034 2021-03-15 op exists. I myself routinely switch between a couple of them, depending
32 cd302034 2021-03-15 op on my mood.
33 cd302034 2021-03-15 op
34 cd302034 2021-03-15 op More browsers brings more stability as it became more difficult to
35 cd302034 2021-03-15 op change the protocol, too.
36 cd302034 2021-03-15 op
37 cd302034 2021-03-15 op However, Telescope was ultimately written for fun, on a whim, just to
38 cd302034 2021-03-15 op play with ncurses, libtls, libevent and the macros from `sys/queue.h`,
39 cd302034 2021-03-15 op but I'd like to finish it into a complete Gemini browser.
40 cd302034 2021-03-15 op
41 cd302034 2021-03-15 op
42 cd302034 2021-03-15 op ## Goals
43 cd302034 2021-03-15 op
44 cd302034 2021-03-15 op - Fun: hacking on Telescope should be fun.
45 cd302034 2021-03-15 op - Clean: write readable and clean code mostly following the style(9)
46 cd302034 2021-03-15 op guideline. Don't become a kitchen sink.
47 cd302034 2021-03-15 op - Secure: write secure code with privilege separation to mitigate the
48 cd302034 2021-03-15 op security risks of possible bugs.
49 cd302034 2021-03-15 op - Fast: it features a modern, fast, event-based asynchronous I/O
50 018a3114 2021-07-03 op model.
51 656b4b64 2021-03-16 op - Cooperation: re-use existing conventions to allow inter-operations
52 656b4b64 2021-03-16 op and easy migrations from/to other clients.
53 cd302034 2021-03-15 op
54 cd302034 2021-03-15 op
55 3be78a24 2021-03-17 op ## TOFU
56 3be78a24 2021-03-17 op
57 3be78a24 2021-03-17 op Telescope aims to use the "Trust, but Verify (where appropriate)"
58 3be78a24 2021-03-17 op approach outlined here:
59 3be78a24 2021-03-17 op [gemini://thfr.info/gemini/modified-trust-verify.gmi](gemini://thfr.info/gemini/modified-trust-verify.gmi).
60 3be78a24 2021-03-17 op
61 3be78a24 2021-03-17 op The idea is to define three level of verification for a certificate:
62 3be78a24 2021-03-17 op
63 3be78a24 2021-03-17 op - **untrusted**: the server fingerprint does NOT match the stored
64 3be78a24 2021-03-17 op value
65 3be78a24 2021-03-17 op - **trusted**: the server fingerprint matches the stored one
66 3be78a24 2021-03-17 op - **verified**: the fingerprint matches and has been verified
67 3be78a24 2021-03-17 op out-of-band by the client.
68 3be78a24 2021-03-17 op
69 3be78a24 2021-03-17 op Most of the time, the `trusted` level is enough, but where is
70 3be78a24 2021-03-17 op appropriate users should be able to verify out-of-band the
71 3be78a24 2021-03-17 op certificate.
72 3be78a24 2021-03-17 op
73 018a3114 2021-07-03 op At the moment there is no UI for oob-verification though.
74 3be78a24 2021-03-17 op
75 3be78a24 2021-03-17 op
76 4def0885 2021-03-12 op ## Building
77 4def0885 2021-03-12 op
78 4def0885 2021-03-12 op Telescope depends on ncursesw, libtls (from either LibreSSL or
79 364730f4 2022-02-20 op libretls), libevent (either v1 or v2) and pkg-config. When building
80 364730f4 2022-02-20 op from a git checkout, yacc (or bison) is also needed.
81 4def0885 2021-03-12 op
82 97e30cc6 2021-03-14 op To build from a release tarball just execute:
83 4def0885 2021-03-12 op
84 94e6f532 2022-05-09 op $ ./configure
85 94e6f532 2022-05-09 op $ make
86 94e6f532 2022-05-09 op $ sudo make install
87 4def0885 2021-03-12 op
88 7eaf997f 2021-08-19 op The configure script has optional support for building with libraries
89 94e6f532 2022-05-09 op provided by your distribution instead of using the bundled versions:
90 7eaf997f 2021-08-19 op
91 86ce72db 2021-08-19 op - `--with-libbsd`: link with [libbsd](https://libbsd.freedesktop.org)
92 7eaf997f 2021-08-19 op - `--with-libimsg`: link with the
93 7eaf997f 2021-08-19 op [imsg-compat](https://github.com/bsd-ac/imsg-compat) library
94 7eaf997f 2021-08-19 op
95 4def0885 2021-03-12 op If you want to build from the git checkout, something that's
96 cd302034 2021-03-15 op discouraged for users that don't intend to hack on telescope
97 4def0885 2021-03-12 op
98 94e6f532 2022-05-09 op $ ./autogen.sh
99 94e6f532 2022-05-09 op $ ./configure
100 94e6f532 2022-05-09 op $ make
101 94e6f532 2022-05-09 op $ sudo make install # eventually
102 4def0885 2021-03-12 op
103 4def0885 2021-03-12 op Please keep in mind that the main branch, from time to time, may be
104 4def0885 2021-03-12 op accidentally broken on some platforms. Telescope is developed
105 4def0885 2021-03-12 op primarily on OpenBSD/amd64 and commits on the main branch don't get
106 4def0885 2021-03-12 op always tested in other OSes. Before tagging a release however, a
107 61105165 2022-03-29 op comprehensive testing on various platforms is done to ensure
108 61105165 2022-03-29 op everything is working as intended.
109 4def0885 2021-03-12 op
110 4def0885 2021-03-12 op
111 908345fb 2021-08-28 op ## Contributing
112 c6cad9e5 2021-07-17 op
113 c6cad9e5 2021-07-17 op Any form of contribution is appreciated, not only patches or bug
114 908345fb 2021-08-28 op reports: feel free to open an issue or send an email to
115 908345fb 2021-08-28 op `telescope@omarpolo.com`.
116 c6cad9e5 2021-07-17 op
117 908345fb 2021-08-28 op If you have a sample configuration, custom theme, a script or anything
118 61105165 2022-03-29 op that could be helpful to others, consider adding it to the `contrib`
119 61105165 2022-03-29 op directory.
120 c6cad9e5 2021-07-17 op
121 908345fb 2021-08-28 op
122 afa57f78 2021-07-15 op ## User files
123 afa57f78 2021-07-15 op
124 73389b00 2021-10-08 op Telescope stores user files according to the [XDG Base Directory
125 73389b00 2021-10-08 op Specification][xdg] by default. The usage and contents of these files
126 eb2ed626 2021-10-07 op are described in [the man page](telescope.1), under "FILES".
127 afa57f78 2021-07-15 op
128 afa57f78 2021-07-15 op Only one instance of Telescope can be running at time per user.
129 afa57f78 2021-07-15 op
130 afa57f78 2021-07-15 op
131 4def0885 2021-03-12 op ## License
132 4def0885 2021-03-12 op
133 4def0885 2021-03-12 op Telescope is distributed under a BSD-style licence. The main code is
134 3d7d29b3 2021-08-13 op under the ISC but for files under `compat/` it varies.
135 bf6551ee 2021-07-18 op
136 bf6551ee 2021-07-18 op `data/emoji.txt` is copyright © 1991-2021 Unicode, Inc. and
137 61105165 2022-03-29 op distributed under the [UNICODE, Inc license
138 61105165 2022-03-29 op agreement][unicode-license].
139 bf6551ee 2021-07-18 op
140 bf6551ee 2021-07-18 op
141 bf6551ee 2021-07-18 op [unicode-license]: https://www.unicode.org/license.html
142 73389b00 2021-10-08 op [xdg]: https://specifications.freedesktop.org/basedir-spec/latest/