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