README.txt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448
  1. ━━━━━━━━
  2. TINMOP
  3. ━━━━━━━━
  4. Table of Contents
  5. ─────────────────
  6. 1. Introduction
  7. 2. Peculiar Features
  8. .. 1. Important note
  9. 3. Dependency
  10. .. 1. Programs
  11. .. 2. Lisp Libraries
  12. .. 3. Foreign (C language) library
  13. 4. Install
  14. .. 1. Using guix
  15. .. 2. From source
  16. 5. Usage
  17. 6. BUGS
  18. 7. Translations
  19. 8. License
  20. 9. Privacy
  21. 10. Contributing
  22. 11. FAQ
  23. 12. NO WARRANTY
  24. 13. Acknowledgment
  25. 1 Introduction
  26. ══════════════
  27. Tinmop is an opinionated client for [Pleroma] (using the mastodon API)
  28. and [gemini protocol]. It offer a distraction free terminal
  29. interface.
  30. The name is a recursive acronym: "Tinmop Is Not Mutt or Pine". The
  31. older of us can remember that, in turn, Pine is sometimes considered
  32. an acronym as well: "Pine Is Not Elm" and, finally, Elm means
  33. (according to Wikipedia): "Electronic Mail".
  34. [Pleroma] <https://pleroma.social/>
  35. [gemini protocol] <https://gemini.circumlunar.space/>
  36. 2 Peculiar Features
  37. ═══════════════════
  38. • tree structure of messages;
  39. • subscriptions of hashtag;
  40. • programmable and extensible;
  41. • encrypted direct message (but see 11);
  42. • no mentions notification, no knowledge of when or who favourited
  43. your status;
  44. • No blocking or muting, the client can be configured to ignore a list
  45. of accounts.
  46. 2.1 Important note
  47. ──────────────────
  48. This is alpha quality software, many things are broken, some feature
  49. are missing some works with unintended/unexpected side effects; this
  50. software is for testing only and remember that there is [NO WARRANTY].
  51. [NO WARRANTY] See section 12
  52. 3 Dependency
  53. ════════════
  54. 3.1 Programs
  55. ────────────
  56. ⁃ to build the package: xgettext.
  57. ⁃ to install the package, including running the script to install lisp
  58. libraries (`quick_quicklisp.sh'):
  59. • AWK;
  60. • BASH shell.
  61. ⁃ to run the program:
  62. • SBCL compiler;
  63. • xdg-open;
  64. • openssl;
  65. • your favourite editor (default: nano).
  66. All the dependencies above should be available using the package
  67. manager of your distribution (`apt', `yum' etc).
  68. 3.2 Lisp Libraries
  69. ──────────────────
  70. • alexandria;
  71. • cl-ppcre;
  72. • tooter;
  73. • croatoan;
  74. • osicat;
  75. • cl-spark;
  76. • access;
  77. • sqlite;
  78. • sxql;
  79. • sxql-composer;
  80. • marshal;
  81. • bordeaux-threads;
  82. • log4cl;
  83. • local-time;
  84. • cl-colors2;
  85. • cl-i18n;
  86. • clunit2;
  87. • esrap;
  88. • ieee-floats;
  89. • parse-number;
  90. • cl-html5-parser;
  91. • unix-opts;
  92. • crypto-shortcuts;
  93. • drakma.
  94. All these libraries will be downloaded, compiled and installed by the
  95. script `quick_quicklisp.sh', see below.
  96. 3.3 Foreign (C language) library
  97. ────────────────────────────────
  98. • libssl (TLS socket)
  99. The C library should be installed with their header (`*.h') files.
  100. On Debian or derived system this means installing the library
  101. package with the `-dev' suffix as shown below:
  102. ┌────
  103. │ # apt-get install libssl-dev
  104. └────
  105. 4 Install
  106. ═════════
  107. 4.1 Using guix
  108. ──────────────
  109. Using [guix] is the simpler way to install this software:
  110. ┌────
  111. │ $ guix install tinmop
  112. └────
  113. Guix can be installed on debian (testing or sid):
  114. ┌────
  115. │ $ apt-get install guix
  116. └────
  117. or using a shell script [as explained in the guix manual].
  118. [guix] <https://guix.gnu.org/>
  119. [as explained in the guix manual]
  120. <https://guix.gnu.org/manual/en/guix.html#Binary-Installation>
  121. 4.2 From source
  122. ───────────────
  123. 1. optional step needed only if you have not already the configure
  124. script, you will need `autotools' for that.
  125. ┌────
  126. │ $ autoreconf -fiv
  127. └────
  128. 2. run `configure' and resolve the missing dependencies (if any)
  129. ┌────
  130. │ $ ./configure
  131. └────
  132. 3. the script `quick-quicklisp.sh' will download and install the
  133. library manager and the library on your home dir.
  134. ┌────
  135. │ $ ./quick_quicklisp.sh
  136. └────
  137. This step is optional if you have already installed quicklisp, in
  138. this case just load the [dependencies] using the client installed
  139. on your computer.
  140. 4. clone in `$HOME/quicklisp/local-projects/' the latest version of
  141. croatoan, a library to wrap the ncurses TUI library.
  142. This step is temporary as this version will get into quicklisp
  143. eventually.
  144. ┌────
  145. │ $ cd $HOME/quicklisp/local-projects/
  146. │ $ git clone https://github.com/McParen/croatoan.git
  147. └────
  148. 5. build the executable:
  149. ┌────
  150. │ $ make
  151. └────
  152. 6. install on your system:
  153. ┌────
  154. │ # make install
  155. └────
  156. 7. take a look the manpage:
  157. ┌────
  158. │ $ man tinmop
  159. └────
  160. 8. run the software!
  161. ┌────
  162. │ $ tinmop
  163. └────
  164. 9. An error will be printed about a missing file place a simple
  165. configuration file in one of the directory the software indicated.
  166. See [the FAQ below].
  167. [dependencies] See section 3
  168. [the FAQ below] See section 11
  169. 5 Usage
  170. ═══════
  171. See the command line options:
  172. ┌────
  173. │ $ tinmop -h
  174. └────
  175. To get instruction about configuration:
  176. ┌────
  177. │ $ man tinmop
  178. └────
  179. 6 BUGS
  180. ══════
  181. Please file bug reports on the [notabug repository].
  182. [notabug repository] <https://notabug.org/cage/tinmop/>
  183. 7 Translations
  184. ══════════════
  185. Only Italian translation is regularly updated.
  186. 8 License
  187. ═════════
  188. This program is released under GNU General Public license version 3 or
  189. later (see COPYING file).
  190. The program use data and code from other sources, please see
  191. LICENSES.org for credits.
  192. Although any efforts has been put to make the list of credits
  193. exhaustive, errors are always possible. Please send correction to
  194. cage-dev at twistfold dot it.
  195. 9 Privacy
  196. ═════════
  197. The author of this software collects no user data information with
  198. this software.
  199. But this software is a client to connect and interact to one or more
  200. remote computer. So potentially it could share a lot of information
  201. with other actors but just after the user allowed it to do so.
  202. It is the user responsibility to checks the privacy conditions of the
  203. instance this software connect to.
  204. Moreover launching `quick_quicklisp.sh' will contact
  205. <https://www.quicklisp.org/>, check the [quicklisp sources] for
  206. details.
  207. By default, pressing "!" will contact the remote service located at:
  208. "gemini://geminispace.info/search".
  209. [quicklisp sources] <https://beta.quicklisp.org/quicklisp.lisp>
  210. 10 Contributing
  211. ═══════════════
  212. Any help is appreciated. If you intend to contribute please point your
  213. browser to the [issue tracker] or file a [pull request].
  214. But, please take a minute to read the file <./CONTRIBUTING.org>
  215. [issue tracker] <https://notabug.org/cage/tinmop/issues>
  216. [pull request] <https://notabug.org/cage/tinmop/pulls>
  217. 11 FAQ
  218. ══════
  219. • I just tried to start the program for the first time but it give me
  220. a weird error, what's wrong?
  221. Did you wrote a configuration file before starting?
  222. Tinmop expects a configuration file in your config directory
  223. (usually `$HOME/.config/tinmop/'). This file must contains at least
  224. the username and the name of the instance you want to connect.
  225. Example :
  226. ┌────
  227. │ # a line starting with a '#' is a comment
  228. │ # a file can be included in another with this directive:
  229. │ # use "shared.conf"
  230. │ # The server instance name
  231. │ server = server address
  232. │ # your username
  233. │ username = username
  234. └────
  235. If this file does not exists or is invalid tinmop could be used just
  236. as a gemini client.
  237. Please check the man page (tinmop(1)) for more information.
  238. • The `quick_quicklisp.sh' script failed and refuse to start again,
  239. what can I do?
  240. If tinmop is the first Common lisp program you have ever installed
  241. installed, try to rename the directory `$/HOME/quicklisp' and, then,
  242. restart the script.
  243. If problem persists [contact me].
  244. • Is tinmop compatible with mastodon servers?
  245. Unfortunately no, the way some API endpoint provide the toots is not
  246. suitable for this client, for more information please go [here].
  247. I hope this will change in the future but this depends entirely from
  248. the people are developing the server.
  249. • OK the program is running but how can i use it?
  250. Press the key `?' to get a list of the available keys available.
  251. • Tinmop crashed! Where can i report that?
  252. The issue tracker is here:
  253. <https://notabug.org/tinmop/issues/>
  254. Please also, if possible, send the backtrace of the process. To
  255. print a backtrace just write `backtrace' when the debugger has been
  256. invoked.
  257. *Important note*
  258. The backtrace can contains sensitive and personal information,
  259. please always *carefully checks* the backtrace contents before
  260. making this information public!
  261. • Are the encrypted messages secure?
  262. *No*. First only a symmetric encryption scheme is implemented (so
  263. there is a problem of secure key exchanging). Moreover i am not a
  264. crypto expert and probably i made something wrong. Note that i am
  265. not claiming that the algorithm (AES256) or the implementation of
  266. such encrypting algorithm is flawed but that, likely, is flawed the
  267. code i wrote to use the crypto library in this software.
  268. So, please do not consider the encrypted message secure at all.
  269. [contact me] See section 6
  270. [here] <https://github.com/tootsuite/mastodon/issues/13817>
  271. 12 NO WARRANTY
  272. ══════════════
  273. tinmop: an humble gemini and pleroma client Copyright (C) 2020 cage
  274. This program is free software: you can redistribute it and/or modify
  275. it under the terms of the GNU General Public License as published by
  276. the Free Software Foundation, either version 3 of the License, or (at
  277. your option) any later version.
  278. This program is distributed in the hope that it will be useful, but
  279. WITHOUT ANY WARRANTY; without even the implied warranty of
  280. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  281. General Public License for more details.
  282. You should have received a copy of the GNU General Public License
  283. along with this program. If not, see [http://www.gnu.org/licenses/].
  284. [http://www.gnu.org/licenses/] <http://www.gnu.org/licenses/>
  285. 13 Acknowledgment
  286. ═════════════════
  287. My deep thanks to the folks that provided us with wonderful SBCL and
  288. Common lisp libraries.
  289. In particular i want to thanks the authors of the libraries Croatoan
  290. and Tooter for their help when I started to develop this program.
  291. There are more people i borrowed code and data from, they are
  292. mentioned in the file LINCENSES.org
  293. This program is was born also with the help of CCCP: "Collettivo
  294. Computer Club Palermo".
  295. Also thanks to "barbar" for testing of the installation scripts.