mirror of https://codeberg.org/cage/tinmop/
354 lines
9.9 KiB
Groff
354 lines
9.9 KiB
Groff
.TH "tinmop" "1"
|
|
|
|
.SH "Name"
|
|
.PP
|
|
tinmop - a client for gemini or pleroma social network
|
|
|
|
.SH "Synopsis"
|
|
.PP
|
|
tinmop [OPTION]...
|
|
|
|
.SH "Description"
|
|
.PP
|
|
This document assumes basic knowledge of how fediverse works. More
|
|
information about this topic can be found on the
|
|
official website (\fIhttps://docs.joinmastodon.org/\fP).
|
|
|
|
.PP
|
|
Tinmop proposes a terminal interface to connect with Pleroma
|
|
social network and as client for the gemini protocol
|
|
|
|
.PP
|
|
gemini://gemini.circumlunar.space/
|
|
|
|
.SH "Options"
|
|
.PP
|
|
Without options the program will start a terminal interface and will
|
|
try to connect to your instance (see \fIConfiguration\fP)
|
|
|
|
.TP
|
|
\fB-o, --open-gemini-url ARG \fP
|
|
Open gemini url
|
|
.TP
|
|
\fB-m, --notify-mentions ARG \fP
|
|
Notify messages that mentions the user
|
|
.TP
|
|
\fB-R, --reset-timeline-pagination \fP
|
|
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
|
|
.TP
|
|
\fB-c, --check-follows-requests \fP
|
|
Checks for follow request at start
|
|
.TP
|
|
\fB-e, --execute-script SCRIPT-FILE\fP
|
|
Execute a script file
|
|
.TP
|
|
\fB-f, --folder FOLDER-NAME \fP
|
|
Start on that folder
|
|
.TP
|
|
\fB-h, --help \fP
|
|
print program help and exit
|
|
.TP
|
|
\fB-t, --timeline TIMELINE-NAME \fP
|
|
Start using this timeline
|
|
.TP
|
|
\fB-u, --update-timeline \fP
|
|
Update the selected timeline
|
|
.TP
|
|
\fB-v, --version \fP
|
|
Print program version and exit
|
|
|
|
.SH "Usage"
|
|
.PP
|
|
Users of Tinmop supposed to interact with the social network
|
|
using a terminal interface (TUI), The terminal screen layout is
|
|
sketched below:
|
|
|
|
.RS
|
|
.nf
|
|
\fC+---------------+---------------------------+
|
|
| | |
|
|
| tags window | thread windows |
|
|
| | |
|
|
| | modeline |
|
|
+---------------+---------------------------+
|
|
| | |
|
|
| conversations | main window |
|
|
| window | |
|
|
| | |
|
|
| | |
|
|
+---------------+---------------------------+
|
|
| command window |
|
|
+-------------------------------------------+
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
The screen is subdivided in five window:
|
|
|
|
.TP
|
|
\fBtag window\fP
|
|
shows the tag users subscribed for and available
|
|
.PP
|
|
messages for each tag;
|
|
|
|
.TP
|
|
\fBthreads window\fP
|
|
for a given timeline and folder (see
|
|
.PP
|
|
\fIFolders\fP) show the discussions saved in user's local database;
|
|
|
|
.TP
|
|
\fBconversations window\fP
|
|
show the \fIprivate\fP conversations the user is having with others;
|
|
|
|
.TP
|
|
\fBmain window\fP
|
|
show the body of the message selected in the tag window or gemini page
|
|
|
|
.TP
|
|
\fBcommand window\fP
|
|
the window where the user instruct the software to perform commands
|
|
|
|
.PP
|
|
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 \fC?\fP (if this keybinding has not been
|
|
customized).
|
|
|
|
.SS "Folders"
|
|
.PP
|
|
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.
|
|
|
|
.SH "Configuration"
|
|
.PP
|
|
The configuration of tinmop is based on text files but there are
|
|
available two different kind with different syntax and scope.
|
|
|
|
.IP \(em 4
|
|
a key-value text files used to configure the access credential to
|
|
.PP
|
|
server and visual theme of the program (simple configuration);
|
|
|
|
.IP \(em 4
|
|
common lisp source code. Used to write module (AKA plugin) and to
|
|
.PP
|
|
configure keybindings to interact with the software.
|
|
|
|
.PP
|
|
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.
|
|
|
|
.SS "Simple configuration"
|
|
.PP
|
|
This is a simple file with each entry in a single line that look like this:
|
|
|
|
.RS
|
|
.nf
|
|
\fC
|
|
# 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
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
As you can see a line starting with a \fB#\fP is considered comment and
|
|
skipped by the program
|
|
|
|
.PP
|
|
The file with this credential are confidential and must be put into
|
|
user's home directory under the path
|
|
\fC$HOME/.local/share/tinmop/main.conf\fP. Probably the directory
|
|
\fCtinmop\fP does not exists on user system, if it does not exists must
|
|
be created manually.
|
|
|
|
.PP
|
|
If the program was installed correctly two other files with simple
|
|
semantics are located in your system wide configuration directory
|
|
(usually \fC/etc/tinmop/\fP), please check these files for more
|
|
information, as they are extensively commented.
|
|
|
|
.SS "Lisp program"
|
|
.PP
|
|
These files contains Common lisp (see \fIhttps://common-lisp.net/\fP)
|
|
source code. And are used both as a way to configure the program
|
|
and to write module for tinmop itself.
|
|
|
|
.PP
|
|
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!).
|
|
|
|
.PP
|
|
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
|
|
\fBsevere\fP security damage.
|
|
|
|
.PP
|
|
Again in the configuration directory there is a (commented) file
|
|
named \fCinit.lisp\fP 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 \fC$HOME/.local/share/tinmop/\fP or
|
|
\fC$HOME/.config/tinmop/\fP (because, you know, data is code and code
|
|
is data) to be successfully loaded.
|
|
|
|
.PP
|
|
However there is no need to write their own init file if user is
|
|
happy with the provided one by the package maintainers.
|
|
|
|
.SH "First time start"
|
|
.PP
|
|
After the configuration the program can be started but we are not
|
|
ready to join the network yet because tinmop need to be \fItrusted\fP 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).
|
|
|
|
.SH "How to get more help"
|
|
.PP
|
|
For help with pleroma visit the pleroma website:
|
|
|
|
.PP
|
|
\fIhttps://pleroma.social/\fP
|
|
|
|
.PP
|
|
For information about gemini:
|
|
|
|
.PP
|
|
$ tinmop -o gemini://gemini.circumlunar.space
|
|
|
|
.PP
|
|
The program has an inline help (default binding for help is "?")
|
|
|
|
.PP
|
|
You can search the help strings with a command (default: "C-h a").
|
|
|
|
.PP
|
|
Moreover you can have some useful hint at the program web page:
|
|
|
|
.PP
|
|
[\fIhttps://www.autistici.org/interzona/tinmop/\fP]
|
|
|
|
.SH "BUGS"
|
|
.PP
|
|
There are many, totally unknown, hiding in the code! Please help the
|
|
programmer to nail them using the
|
|
https://notabug.org/cage/tinmop/issues/ \fBat\fP \fIissue tracker\fP.
|
|
|
|
.SH "Contributing"
|
|
.PP
|
|
There is always need for help, you can join the developer, sending
|
|
patches or translating the UI to your favourite language.
|
|
|
|
.PP
|
|
Just point your browser to the
|
|
https://notabug.org/cage/tinmop/ \fBat\fP \fIcode repository\fP.
|
|
|
|
.PP
|
|
See also the file CONTRIBUTE.org
|
|
|
|
.SS "Debug mode"
|
|
.PP
|
|
If you decomment the line:
|
|
|
|
.RS
|
|
.nf
|
|
\fC;;(push :debug-mode *features*)
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
The program will be compiled in \fCdebug\-mode\fP this means that a lot
|
|
of diagnostic output will be appended to a file named \fCtinmop.log\fP
|
|
in the directory \fC$HOME/.local/share/tinmop/\fP.
|
|
|
|
.SH "Files"
|
|
.IP \(em 4
|
|
\fC$HOME/.local/share/tinmop/db.sqlite3\fP: the program database
|
|
.IP \(em 4
|
|
\fC$HOME/.local/share/tinmop/client\fP: the program credentials to connect with the instance \fBkeep private!\fP
|
|
.IP \(em 4
|
|
\fC$HOME/.local/share/tinmop/tinmop.log\fP: this file is created only for debugging and should not be enabled in binary package distribution (see \fIContributing\fP).
|
|
.IP \(em 4
|
|
\fC/etc/tinmop/default\-theme.conf\fP: default visual style
|
|
.IP \(em 4
|
|
\fC/etc/tinmop/shared.conf\fP: some default configuration not related to themes
|
|
.IP \(em 4
|
|
\fC/etc/tinmop/init.lisp\fP: system wide configuration
|
|
.IP \(em 4
|
|
\fC$HOME/.config/tinmop/init.lisp\fP: user configuration
|
|
.IP \(em 4
|
|
\fC$HOME/.config/tinmop/main.conf\fP: user configuration (simple format)
|
|
|
|
.SH "Privacy"
|
|
.PP
|
|
The author of this software collects no user data information with
|
|
this software.
|
|
|
|
.PP
|
|
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.
|
|
|
|
.PP
|
|
It is the user responsibility to checks the privacy conditions of the
|
|
instance this software connect to.
|
|
|
|
.PP
|
|
By default, pressing "!" will contact the remote service located at:
|
|
"gemini://houston.coder.town/search".
|
|
|
|
.PP
|
|
Moreover launching \fCquick_quicklisp.sh\fP will contact
|
|
\fIhttps://www.quicklisp.org/\fP, check the
|
|
https://beta.quicklisp.org/quicklisp.lisp \fBat\fP \fIquicklisp sources\fP for
|
|
details.
|
|
|
|
.SH "Acknowledgment"
|
|
.PP
|
|
My deep thanks to the folks that provided us with wonderful SBCL and
|
|
Common lisp libraries.
|
|
|
|
.PP
|
|
In particular i want to thanks the authors of the libraries Croatoan and Tooter
|
|
for their help when I started to develop this program.
|
|
|
|
.PP
|
|
There are more people i borrowed code and data from, they are mentioned
|
|
in the file LINCENSES.org
|
|
|
|
.PP
|
|
This program is was born also with the help of CCCP: "Collettivo Computer
|
|
Club Palermo".
|
|
|
|
.PP
|
|
Also thanks to "barbar" for testing of the installation scripts.
|