1
0
mirror of https://codeberg.org/cage/tinmop/ synced 2024-12-13 22:46:13 +01:00
tinmop/README.org

328 lines
11 KiB
Org Mode
Raw Normal View History

2020-05-08 15:45:43 +02:00
#+OPTIONS: html-postamble:nil html-preamble:nil
#+AUTHOR:
#+TITLE: tinmop
#+BEGIN_EXPORT html
<a href="https://translate.codeberg.org/engage/tinmop/">
<img src="https://translate.codeberg.org/widgets/tinmop/-/svg-badge.svg" alt="Translation status" />
</a>
#+END_EXPORT
2020-05-08 15:45:43 +02:00
* Introduction
2023-10-19 18:20:49 +02:00
Tinmop is an opinionated client for [[https://gemini.circumlunar.space/][gemini protocol]], Gopher,
[[https://joinmastodon.org/][Mastodon]], [[https://pleroma.social/][Pleroma]] (using the mastodon API) and [[https://kamid.omarpolo.com/][kamid]] protocols. It offer a
distraction free terminal interface and a GUI for connecting to the geminispace.
The name is a recursive acronym: "Tinmop Is Not Mutt or Pine". The older of us can remember that, in turn, Pine is sometimes considered
an acronym as well: "Pine Is Not Elm" and, finally, Elm means (according to Wikipedia): "Electronic Mail".
2020-05-08 15:45:43 +02:00
* Peculiar Features
- tree structure of messages;
- subscriptions of hashtag;
2020-05-16 19:13:33 +02:00
- programmable and extensible;
2020-05-08 15:45:43 +02:00
- encrypted direct message (but see [[FAQ]]);
2023-10-19 18:20:49 +02:00
- no mentions notification, no knowledge of when or who favourited your status;
- No blocking or muting, the client can be configured to ignore a list of accounts.
2020-05-08 15:45:43 +02:00
2020-05-16 15:24:29 +02:00
** Important note
2023-10-19 18:20:49 +02:00
This is alpha quality software, many things are broken, some feature are missing some works with unintended/unexpected side
effects; this software is for testing only and remember that there is [[NO WARRANTY][NO WARRANTY]].
2020-05-16 15:24:29 +02:00
2020-05-08 15:45:43 +02:00
* Dependency
** Programs
+ to build the package:
- C compiler
- SBCL compiler;
- curl
- xgettext.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
+ to install the package, including running the script to install lisp libraries (~quick_quicklisp.sh~):
2021-02-26 20:41:05 +01:00
- AWK;
- git.
2020-05-08 15:45:43 +02:00
+ to run the program:
- xdg-open;
- openssl;
- unzip (command line utility to decompress zip file);
- TK wish interpreter;
- your favourite editor (default: nano).
2022-12-10 14:49:53 +01:00
+ optional recommended programs:
- man
- imagemagick
2023-10-19 18:20:49 +02:00
All the dependencies above should be available using the package manager of your distribution (~apt~, ~yum~ etc).
2021-01-03 17:55:02 +01:00
2020-05-08 15:45:43 +02:00
** Lisp Libraries
2023-10-19 18:20:49 +02:00
2020-05-08 15:45:43 +02:00
- access;
- alexandria;
- babel;
2020-05-08 15:45:43 +02:00
- bordeaux-threads;
- cl+ssl;
- cl-base64;
2020-05-08 15:45:43 +02:00
- cl-colors2;
- cl-html5-parser;
2020-05-08 15:45:43 +02:00
- cl-i18n;
- cl-ppcre-unicode;
- cl-spark;
2020-05-08 15:45:43 +02:00
- clunit2;
- croatoan;
- crypto-shortcuts;
- drakma;
2020-05-08 15:45:43 +02:00
- esrap;
- flexi-streams;
2020-05-08 15:45:43 +02:00
- ieee-floats;
- local-time;
- log4cl;
- marshal;
- nodgui;
2020-05-08 15:45:43 +02:00
- parse-number;
- percent-encoding;
- purgatory;
- sqlite;
- sxql;
- sxql-composer;
- tooter;
- trivial-clipboard;
- uiop;
2020-05-08 15:45:43 +02:00
- unix-opts;
- usocket;
- yason.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
All these libraries will be downloaded, compiled and installed by the script ~quick_quicklisp.sh~, see below.
2021-01-03 17:55:02 +01:00
2020-05-08 15:45:43 +02:00
** Foreign (C language) library
- libssl (TLS socket)
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
The C library should be installed with their header (~*.h~) files. On Debian or derived system this means installing the library package with the ~-dev~ suffix as shown below:
#+BEGIN_SRC sh
# apt-get install libssl-dev
#+END_SRC
*** Indirect foreign dependencies
These library are not directly required by tinmop, but are needed nevertheless to make the GUI library ([[https://www.autistici.org/interzona/nodgui.html][nodgui]]) works.
#+BEGIN_SRC sh
# apt-get install tk libturbojpeg0-dev
#+END_SRC
Note that, at the moment, the ~quick_quicklisp.sh~ script will *not* install the foreign dependencies.
2020-05-08 15:45:43 +02:00
* Install
** Using guix
Using [[https://guix.gnu.org/][guix]] is the simpler way to install this software:
#+BEGIN_SRC sh
$ guix pull && guix package -u && guix install tinmop
#+END_SRC
Guix can be installed on debian (testing or sid):
#+BEGIN_SRC sh
$ apt-get install guix
#+END_SRC
or using a shell script [[https://guix.gnu.org/manual/en/guix.html#Binary-Installation][as explained in the guix manual]].
** From source
2023-10-19 18:20:49 +02:00
1. optional step needed only if you have not already the configure script, you will need ~autotools~ for that.
2020-05-08 15:45:43 +02:00
#+BEGIN_SRC sh
$ autoreconf -fiv
#+END_SRC
2. run ~configure~ and resolve the missing dependencies (if any)
#+BEGIN_SRC sh
$ ./configure
#+END_SRC
3. the script ~quick-quicklisp.sh~ will download and install the library manager and the lisp libraries on your home dir.
2020-05-08 15:45:43 +02:00
#+BEGIN_SRC sh
$ ./quick_quicklisp.sh
#+END_SRC
2023-10-19 18:20:49 +02:00
This step is optional if you have already installed quicklisp, in this case just load the [[Dependency][dependencies]] using the client installed on your computer.
2020-05-08 15:45:43 +02:00
4. optional step if you did not ran ~quick-quicklisp.sh~.
2023-10-19 18:20:49 +02:00
Clone in ~$HOME/quicklisp/local-projects/~ the latest version of croatoan, a library to wrap the ncurses TUI library.
2020-05-11 20:43:13 +02:00
This step is temporary as this version will get into quicklisp eventually.
2023-10-19 18:20:49 +02:00
2020-05-11 20:43:13 +02:00
#+BEGIN_SRC sh
$ cd $HOME/quicklisp/local-projects/
2024-09-26 21:29:14 +02:00
$ git clone https://codeberg.org/McParen/croatoan.git
2020-05-11 20:43:13 +02:00
#+END_SRC
5. build the executable:
2020-05-08 15:45:43 +02:00
#+BEGIN_SRC sh
$ make
#+END_SRC
6. install on your system:
2020-05-08 15:45:43 +02:00
#+BEGIN_SRC sh
# make install
2020-05-08 15:45:43 +02:00
#+END_SRC
2021-01-03 17:55:02 +01:00
7. take a look the manpage:
#+BEGIN_SRC sh
$ man tinmop
#+END_SRC
8. run the software!
2020-05-08 15:45:43 +02:00
#+BEGIN_SRC sh
$ tinmop
#+END_SRC
2023-10-19 18:20:49 +02:00
9. An error will be printed about a missing file place a simple configuration file in one of the directory the software indicated. See [[FAQ][the FAQ below]].
2021-01-04 21:41:49 +01:00
2020-05-08 15:45:43 +02:00
* Usage
See the command line options:
#+BEGIN_SRC sh
$ tinmop -h
#+END_SRC
To get instruction about configuration:
#+BEGIN_SRC sh
$ man tinmop
#+END_SRC
* BUGS
Please file bug reports on the
2023-06-20 19:57:30 +02:00
[[https://codeberg.org/cage/tinmop/][repository]].
2020-05-08 15:45:43 +02:00
* Translations
Only Italian translation is regularly updated.
To help with translations please go [[https://translate.codeberg.org/engage/tinmop/][here]].
2020-05-08 15:45:43 +02:00
* License
2023-10-19 18:20:49 +02:00
This program is released under GNU General Public license version 3 or later (see COPYING file).
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
The program use data and code from other sources, please see LICENSES.org for credits.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
Although any efforts has been put to make the list of credits exhaustive, errors are always possible. Please send correction to cage-dev at twistfold dot it.
2020-05-08 15:45:43 +02:00
* Privacy
2023-10-19 18:20:49 +02:00
The author of this software collects no user data information with this software.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
But this software is a client to connect and interact to one or more remote computer. So potentially it could share a lot of information with other actors but just after the user allowed it to do so.
2023-10-19 18:20:49 +02:00
It is the user responsibility to checks the privacy conditions of the instance this software connect to.
2023-10-19 18:20:49 +02:00
Moreover launching ~quick_quicklisp.sh~ will contact [[https://www.quicklisp.org/]], check the [[https://beta.quicklisp.org/quicklisp.lisp][quicklisp sources]] for details.
2020-05-08 15:45:43 +02:00
By default, pressing "!" will contact the remote service located at: "gemini://kennedy.gemi.dev/search".
2020-05-08 15:45:43 +02:00
* Contributing
2023-10-19 18:20:49 +02:00
Any help is appreciated. If you intend to contribute please point your browser to the [[https://codeberg.org/cage/tinmop/issues][issue tracker]] or file a [[https://codeberg.org/cage/tinmop/pulls][pull request]].
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
But, please, take a minute to read the file [[./CONTRIBUTING.org]] before
2020-05-08 15:45:43 +02:00
* FAQ
2023-10-19 18:20:49 +02:00
- I just tried to start the program for the first time but it give me a weird error, what's wrong?
2021-01-04 21:41:49 +01:00
Did you wrote a configuration file before starting?
2023-10-19 18:20:49 +02:00
Tinmop expects a configuration file in your config directory (usually ~$HOME/.config/tinmop/~). This file must contains at least the username and the name of the instance you want to connect.
2021-01-04 21:41:49 +01:00
Example :
#+BEGIN_SRC text
# a line starting with a '#' is a comment
# a file can be included in another with this directive:
# use "shared.conf"
# The server instance name
server = server address
# your username
username = username
#+END_SRC
2023-10-19 18:20:49 +02:00
If this file does not exists or is invalid tinmop could be used just as a gemini client.
2021-01-04 21:41:49 +01:00
Please check the man page (tinmop(1)) for more information.
2023-10-19 18:20:49 +02:00
- The ~quick_quicklisp.sh~ script failed and refuse to start again, what can I do?
2021-01-03 17:55:02 +01:00
2023-10-19 18:20:49 +02:00
If tinmop is the first Common lisp program you have ever installed installed, try to rename the directory ~$/HOME/quicklisp~ and, then, restart the script.
2021-01-03 17:55:02 +01:00
If problem persists [[BUGS][contact me]].
- Is tinmop compatible with mastodon servers?
2023-10-19 18:20:49 +02:00
Yes, in fact I am using tinmop with a Mastodon istance on a daily basis.
- OK the program is running but how can i use it?
Press the key ~?~ to get a list of the available keys available.
- Tinmop crashed! Where can i report that?
The issue tracker is here:
2023-06-20 19:57:30 +02:00
[[https://codeberg.org/cage/tinmop/issues/]]
2023-10-19 18:20:49 +02:00
Please also, if possible, send the backtrace of the process. To print a backtrace just write ~backtrace~ when the debugger has been invoked.
*Important note*
2023-10-19 18:20:49 +02:00
The backtrace can contains sensitive and personal information, please always *carefully checks* the backtrace contents before making this information public!
- Are the encrypted messages secure?
2023-10-19 18:20:49 +02:00
*No*. First only a symmetric encryption scheme is implemented (so there is a problem of secure key exchanging). Moreover i am not a crypto expert and probably i made something wrong. Note that i am not claiming that the algorithm (AES256) or the implementation of such encrypting algorithm is flawed but that, likely, is flawed the code i wrote to use the crypto library in this software.
2020-05-08 15:45:43 +02:00
So, please do not consider the encrypted message secure at all.
* NO WARRANTY
2023-10-19 18:20:49 +02:00
tinmop: a multiprotocol client
Copyright © cage
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
2020-05-08 15:45:43 +02:00
2023-10-19 18:20:49 +02:00
You should have received a copy of the GNU General Public License along with this program. If not, see [[http://www.gnu.org/licenses/][http://www.gnu.org/licenses/]].
2020-05-10 19:29:59 +02:00
* Acknowledgment
2023-10-19 18:20:49 +02:00
My deep thanks to the folks that provided us with wonderful SBCL and Common lisp libraries.
2020-05-10 19:29:59 +02:00
2023-10-19 18:20:49 +02:00
In particular i want to thanks the authors of the libraries Croatoan and Tooter for their help when I started to develop this program.
2020-05-10 19:29:59 +02:00
There are more people i borrowed code and data from, they are mentioned in the file LICENSES.org
2020-05-10 19:29:59 +02:00
2023-10-19 18:20:49 +02:00
This program is was born also with the help of CCCP: "Collettivo Computer Club Palermo".
2020-05-16 14:57:48 +02:00
Also thanks to "barbar" for testing of the installation scripts.