1
0
Fork 0
tinmop/doc/tinmop.man

338 lines
9.6 KiB
Groff
Raw Normal View History

2020-05-08 15:45:43 +02:00
.TH "tinmop" "1"
.SH "Name"
.PP
tinmop - a client for mastodon or pleroma social network
.SH "Synopsis"
.PP
tinmop [OPTION]...
.SH "Description"
.PP
2020-06-07 12:38:25 +02:00
This document assumes basic knowledge of how fediverse works. More
information about this topic can be found on the
2020-05-08 15:45:43 +02:00
official website (\fIhttps://docs.joinmastodon.org/\fP).
.PP
2020-05-24 19:17:28 +02:00
Tinmop proposes a terminal interface to connect with Pleroma
social network
2020-05-08 15:45:43 +02:00
.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
2020-06-07 12:38:25 +02:00
.TP
\fB-m, --notify-mentions ARG \fP
Notify messages that mentions the user
2020-05-08 15:45:43 +02:00
.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
2020-05-08 15:45:43 +02:00
.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
2020-05-08 15:45:43 +02:00
.TP
\fB-t, --timeline TIMELINE-NAME \fP
Start using this timeline
.TP
\fB-u, --update-timeline \fP
Update the selected timeline
2020-05-08 15:45:43 +02:00
.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
2020-05-08 15:45:43 +02:00
sketched below:
.RS
.nf
\fC+---------------+---------------------------+
| | |
| tags window | thread windows |
| | |
| | modeline |
+---------------+---------------------------+
| | |
| conversations | message 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
2020-05-08 15:45:43 +02:00
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;
2020-05-08 15:45:43 +02:00
.TP
\fBconversations window\fP
show the \fIprivate\fP conversations the user is having with others;
.TP
\fBmessage window\fP
show the body of the message selected in the tag window
.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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
configure keybindings to interact with the software.
.PP
The distribution of this software comes with a bunch of pre-backed
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
# a file can be included in another with this directive:
# use "shared.conf"
2020-05-08 15:45:43 +02:00
# 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
2020-05-08 15:45:43 +02:00
absolute minimum the user has to provide before starts the program:
the name you chose when you made the account on the server and the
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
\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.
2020-05-08 15:45:43 +02:00
.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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
\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.
2020-05-08 15:45:43 +02:00
.PP
However there is no need to write their own init file if user is
2020-05-08 15:45:43 +02:00
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
2020-05-08 15:45:43 +02:00
that there must be a file with valid credentials available).
.SH "How to get more help"
.PP
For help with mastodon visit the mastodon website.
.PP
The program has an inline help (default binding for help is "?")
.PP
Moreover you can have some useful hint at the program web page:
.PP
[\fIhttps://www.autistici.org/interzona/tinmop/\fP]
2020-05-08 15:45:43 +02:00
.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)
2020-05-08 15:45:43 +02:00
.SH "Privacy"
.PP
The author of this software collects no user data information with
this software.
2020-05-08 15:45:43 +02:00
.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.
2020-05-08 15:45:43 +02:00
.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".
2020-05-16 14:57:48 +02:00
.PP
Also thanks to "barbar" for testing of the installation scripts.