mirror of https://codeberg.org/cage/tinmop/
271 lines
9.9 KiB
Org Mode
271 lines
9.9 KiB
Org Mode
#+TITLE: tinmop
|
|
|
|
* Name
|
|
tinmop - a client for gemini or pleroma social network
|
|
|
|
* Synopsis
|
|
tinmop [OPTION]...
|
|
|
|
* Description
|
|
|
|
This document assumes basic knowledge of how fediverse works. More
|
|
information about this topic can be found on the
|
|
official website ([[https://docs.joinmastodon.org/]]).
|
|
|
|
Tinmop proposes a terminal interface to connect with Pleroma
|
|
social network and as client for the gemini protocol
|
|
|
|
gemini://gemini.circumlunar.space/
|
|
|
|
* Options
|
|
|
|
Without options the program will start a terminal interface and will
|
|
try to connect to your instance (see [[Configuration]]) + -o, --open-gemini-url ARG :: Open gemini url
|
|
+ -m, --notify-mentions ARG :: Notify messages that mentions the user + -R, --reset-timeline-pagination ::
|
|
Reset the timeline pagination. By default the new toots are fetched
|
|
starting from the last one downloaded from the instance, this switch
|
|
will force the program to fetch the last message posted by users
|
|
+ -c, --check-follows-requests :: Checks for follow request at start + -e, --execute-script SCRIPT-FILE :: Execute a script file
|
|
+ -f, --folder FOLDER-NAME :: Start on that folder + -h, --help :: print program help and exit
|
|
+ -t, --timeline TIMELINE-NAME :: Start using this timeline + -u, --update-timeline :: Update the selected timeline
|
|
+ -v, --version :: Print program version and exit
|
|
|
|
* Usage
|
|
|
|
Users of Tinmop supposed to interact with the social network
|
|
using a terminal interface (TUI), The terminal screen layout is
|
|
sketched below:
|
|
|
|
#+NAME: screen-layout
|
|
#+BEGIN_SRC text
|
|
+---------------+---------------------------+
|
|
| | |
|
|
| tags window | thread windows |
|
|
| | |
|
|
| | modeline |
|
|
+---------------+---------------------------+
|
|
| | |
|
|
| conversations | main window |
|
|
| window | |
|
|
| | |
|
|
| | |
|
|
+---------------+---------------------------+
|
|
| command window |
|
|
+-------------------------------------------+
|
|
|
|
#+END_SRC
|
|
|
|
The screen is subdivided in five window:
|
|
|
|
- tag window :: shows the tag users subscribed for and available
|
|
messages for each tag;
|
|
|
|
- threads window :: for a given timeline and folder (see
|
|
[[Folders]]) show the discussions saved in user's local database;
|
|
|
|
- conversations window :: show the /private/ conversations the user is having with others;
|
|
|
|
- main window :: show the body of the message selected in the tag window or gemini page
|
|
|
|
- command window :: the window where the user instruct the software to perform commands
|
|
|
|
The main way to interact with the program is using the keyboard.
|
|
There is a contextual help that appears when the user input data
|
|
that provide hints about commands and a quick help window that can
|
|
be shown by hitting ~?~ (if this keybinding has not been
|
|
customized).
|
|
|
|
** Folders
|
|
|
|
A folder is an object to groups messages for each timeline an
|
|
arbitrary number of folders can be created, when the last message of
|
|
a folder is deleted the folder is deleted as well.
|
|
|
|
* Configuration
|
|
|
|
The configuration of tinmop is based on text files but there are
|
|
available two different kind with different syntax and scope.
|
|
|
|
- a key-value text files used to configure the access credential to
|
|
server and visual theme of the program (simple configuration);
|
|
|
|
- common lisp source code. Used to write module (AKA plugin) and to
|
|
configure keybindings to interact with the software.
|
|
|
|
The distribution of this software comes with a bunch of pre-backed
|
|
configuration files but user is expected to write a simple file with
|
|
their credential to log into the server.
|
|
|
|
** Simple configuration
|
|
|
|
This is a simple file with each entry in a single line that look like this:
|
|
|
|
#+NAME: simple file 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
|
|
|
|
Not incidentally the information in the example above are the
|
|
absolute minimum the user has to provide before starts the program
|
|
and connect to pleroma (to use tinmop as a gemini browser only an
|
|
empty file will suffice): the name you chose when you made the
|
|
account on the server and the address of the server.
|
|
|
|
As you can see a line starting with a *#* is considered comment and
|
|
skipped by the program
|
|
|
|
The file with this credential are confidential and must be put into
|
|
user's home directory under the path ~$HOME/.local/share/tinmop/main.conf~. Probably the directory ~tinmop~ does not exists on user system, if it does not exists must
|
|
be created manually.
|
|
|
|
If the program was installed correctly two other files with simple
|
|
semantics are located in your system wide configuration directory
|
|
(usually ~/etc/tinmop/~), please check these files for more
|
|
information, as they are extensively commented.
|
|
|
|
** Lisp program
|
|
|
|
These files contains Common lisp (see [[https://common-lisp.net/]])
|
|
source code. And are used both as a way to configure the program
|
|
and to write module for tinmop itself.
|
|
|
|
These files are the only way to configure program's keybindings:
|
|
sequence of pressing button to fire command commands (do not worry
|
|
it is not too difficult!).
|
|
|
|
These files must be a valid Common Lisp program to allow the
|
|
program to even starts. Again this is actual source code that is
|
|
loaded end executed by the main program; be careful, do not copy
|
|
and paste code from untrusted sources as this could results in a *severe* security damage.
|
|
|
|
Again in the configuration directory there is a (commented) file
|
|
named ~init.lisp~ that user can use as their starting point to
|
|
write their files. A custom init file, or other module files, must
|
|
be located into the directory ~$HOME/.local/share/tinmop/~ or ~$HOME/.config/tinmop/~ (because, you know, data is code and code
|
|
is data) to be successfully loaded.
|
|
|
|
However there is no need to write their own init file if user is
|
|
happy with the provided one by the package maintainers.
|
|
|
|
* First time start
|
|
|
|
After the configuration the program can be started but we are not
|
|
ready to join the network yet because tinmop need to be /trusted/ by
|
|
the server. Just follows the instruction on screen to register the
|
|
application with your instance. This procedure should be followed
|
|
once: when the program starts for the first time (but please note
|
|
that there must be a file with valid credentials available).
|
|
|
|
* How to get more help
|
|
|
|
For help with pleroma visit the pleroma website:
|
|
|
|
https://pleroma.social/
|
|
|
|
For information about gemini:
|
|
|
|
$ tinmop -o gemini://gemini.circumlunar.space
|
|
|
|
The program has an inline help (default binding for help is "?")
|
|
|
|
You can search the help strings with a command (default: "C-h a").
|
|
|
|
Moreover you can have some useful hint at the program web page:
|
|
|
|
[https://www.autistici.org/interzona/tinmop/]
|
|
|
|
* BUGS
|
|
There are many, totally unknown, hiding in the code! Please help the
|
|
programmer to nail them using the
|
|
[[https://notabug.org/cage/tinmop/issues/][issue tracker]].
|
|
|
|
* Contributing
|
|
|
|
There is always need for help, you can join the developer, sending
|
|
patches or translating the UI to your favourite language.
|
|
|
|
Just point your browser to the
|
|
[[https://notabug.org/cage/tinmop/][code repository]].
|
|
|
|
See also the file CONTRIBUTE.org
|
|
|
|
** Debug mode
|
|
|
|
If you decomment the line:
|
|
|
|
#+BEGIN_SRC lisp
|
|
;;(push :debug-mode *features*)
|
|
#+END_SRC
|
|
|
|
The program will be compiled in ~debug-mode~ this means that a lot
|
|
of diagnostic output will be appended to a file named ~tinmop.log~
|
|
in the directory ~$HOME/.local/share/tinmop/~.
|
|
|
|
* Files
|
|
|
|
- ~$HOME/.local/share/tinmop/db.sqlite3~: the program database
|
|
- ~$HOME/.local/share/tinmop/client~: the program credentials to connect with the instance *keep private!*
|
|
- ~$HOME/.local/share/tinmop/tinmop.log~: this file is created only for debugging and should not be enabled in binary package distribution (see [[Contributing]]).
|
|
- ~/etc/tinmop/default-theme.conf~: default visual style
|
|
- ~/etc/tinmop/shared.conf~: some default configuration not related to themes
|
|
- ~/etc/tinmop/init.lisp~: system wide configuration
|
|
- ~$HOME/.config/tinmop/init.lisp~: user configuration
|
|
- ~$HOME/.config/tinmop/main.conf~: user configuration (simple format)
|
|
|
|
* Privacy
|
|
|
|
The author of this software collects no user data information with
|
|
this software.
|
|
|
|
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.
|
|
|
|
It is the user responsibility to checks the privacy conditions of the
|
|
instance this software connect to.
|
|
|
|
By default, pressing "!" will contact the remote service located at:
|
|
"gemini://houston.coder.town/search".
|
|
|
|
Moreover launching ~quick_quicklisp.sh~ will contact
|
|
[[https://www.quicklisp.org/]], check the
|
|
[[https://beta.quicklisp.org/quicklisp.lisp][quicklisp sources]] for
|
|
details.
|
|
|
|
* Acknowledgment
|
|
|
|
My deep thanks to the folks that provided us with wonderful SBCL and
|
|
Common lisp libraries.
|
|
|
|
In particular i want to thanks the authors of the libraries Croatoan and Tooter
|
|
for their help when I started to develop this program.
|
|
|
|
There are more people i borrowed code and data from, they are mentioned
|
|
in the file LINCENSES.org
|
|
|
|
This program is was born also with the help of CCCP: "Collettivo Computer
|
|
Club Palermo".
|
|
|
|
Also thanks to "barbar" for testing of the installation scripts.
|