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: re-use 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, and pkg-config.
74 [libgrapheme][libgrapheme] is an optional dependency: there's a
75 bundled copy but it's reccomended to install it with a package manager
76 if available.  When building from a git checkout, yacc (or bison) is
77 also needed.
78 
79 To build execute:
80 
81 	$ ./autogen.sh		# only from git checkouts
82 	$ ./configure
83 	$ make
84 	$ sudo make install	# eventually
85 
86 The configure script has optional support for building with libraries
87 provided by your distribution instead of using the bundled versions:
88 
89  - `--with-libbsd`: link with [libbsd][libbsd]
90  - `--with-libimsg`: link with the [imsg-compat][imsg-compat] library
91 
92 [libbsd]:	https://libbsd.freedesktop.org
93 [imsg-compat]:	https://github.com/bsd-ac/imsg-compat
94 [libgrapheme]:	https://libs.suckless.org/libgrapheme/
95 
96 
97 ## Contributing
98 
99 Any form of contribution is appreciated, not only patches or bug
100 reports: feel free to open an issue or send an email to
101 `telescope@omarpolo.com`.
102 
103 If you have a sample configuration, custom theme, a script or anything
104 that could be helpful to others, consider adding it to the `contrib`
105 directory.
106 
107 
108 ## User files
109 
110 Telescope stores user files according to the [XDG Base Directory
111 Specification][xdg] by default.  The usage and contents of these files
112 are described in [the man page](telescope.1), under "FILES".
113 
114 At the moment, only one instance of Telescope can be running at time per
115 user.
116 
117 
118 ## License
119 
120 Telescope is distributed under a BSD-style licence.  The main code is
121 either under the ISC or is Public Domain, but some files under `compat/`
122 are 3-Clause BSD or MIT.  See the first few lines of every file or
123 `about:license` inside telescope for the copyright information.
124 
125 `data/emoji.txt` is copyright © 2022 Unicode, Inc. and distributed
126 under the [UNICODE, Inc license agreement][unicode-license].
127 
128 
129 [unicode-license]: https://www.unicode.org/license.html
130 [xdg]: https://specifications.freedesktop.org/basedir-spec/latest/