mirror of
https://codeberg.org/cage/tinmop/
synced 2024-12-15 22:58:58 +01:00
517 lines
14 KiB
Groff
517 lines
14 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 an extensible terminal interface to connect with
|
|
Pleroma social network or 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 messages for each tag;
|
|
|
|
.TP
|
|
\fBthreads window\fP
|
|
for a given timeline and folder (see \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. By
|
|
default you can move focus to each window (except command window
|
|
that can not get focus explicitly) using \fB'M-arrow key'\fP (meta is
|
|
\fBALT\fP on many keyboards). 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 "Command window keys"
|
|
.PP
|
|
The command window has a few hardcoded command keys to interact
|
|
with it:
|
|
|
|
.IP \(em 4
|
|
the \fBleft\fP and \fBright\fP arrow keys move the cursor;
|
|
.IP \(em 4
|
|
the key \fBhome\fP and \fBend\fP move the cursor to the start and end of
|
|
the input respectively;
|
|
.IP \(em 4
|
|
\fBcanc\fP and \fBbackspace\fP delete the next and previous character
|
|
respectively;
|
|
.IP \(em 4
|
|
the \fBnew line\fP (often called \fBenter\fP key) send the input to the
|
|
program;
|
|
.IP \(em 4
|
|
\fBC-k\fP (that is: "press 'control' and while pressed press 'k')
|
|
\fIkills\fP (deletes) the text from the cursor position to the end of
|
|
the input previously typed;
|
|
.IP \(em 4
|
|
press \fBM-left\fP and \fBM-right\fP (\fBleft alt\fP and \fBleft\fP or \fBright\fP
|
|
arrow together) to browse pages of the suggestion window; the
|
|
suggestion window is a window that holds a previously inputted
|
|
data that are compatible with the string the user is typing into
|
|
the command window;
|
|
.IP \(em 4
|
|
if suggestions are gemini URI press \fBTAB\fP to input the current
|
|
selected suggestion;
|
|
.IP \(em 4
|
|
if suggestion window is \fBnot\fP rendered, pressing \fBup\fP and \fBdown\fP
|
|
arrow keys will cycle through input history, if there is not a
|
|
suggestion window rendered pressing \fBup\fP and \fBdown\fP will scroll
|
|
on suggestions.
|
|
|
|
.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.
|
|
|
|
.PP
|
|
Is worth mentioning again that, without an user configuration file,
|
|
the program can be used as gemini client.
|
|
|
|
.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.
|
|
|
|
.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 fediverse 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).
|
|
|
|
.PP
|
|
There is no additional steps to follow to connect to gemspace,
|
|
instead.
|
|
|
|
.SH "Gempub support"
|
|
.PP
|
|
Tinmop maintains a gempub library scanning a directory on your
|
|
file system (library directory); the library directory path can be
|
|
set using the configuration directive:
|
|
|
|
.RS
|
|
.nf
|
|
\fC
|
|
gempub.directory.library = /absolute/path/to/your/gempub/library
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
the default value is \fC$XDG_DATA_HOME\fP (usually something like
|
|
\fC$HOME/.local/share/tinmop/\fP).
|
|
|
|
.PP
|
|
Using \fB'M-g g l'\fP the library can be inspected using a simple query
|
|
language (similar to SQL) that search in the metadata of the gempub
|
|
files, example of query follows:
|
|
|
|
.RS
|
|
.nf
|
|
\fC
|
|
where author like "calvino" and published < "1980"
|
|
|
|
where author like "cal%" or published = "1980"
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Valid search keys are:
|
|
|
|
.IP \(em 4
|
|
title;
|
|
.IP \(em 4
|
|
author;
|
|
.IP \(em 4
|
|
language;
|
|
.IP \(em 4
|
|
description;
|
|
.IP \(em 4
|
|
publish-date;
|
|
.IP \(em 4
|
|
revision-date;
|
|
.IP \(em 4
|
|
published;
|
|
.IP \(em 4
|
|
copyright.
|
|
|
|
.PP
|
|
You can use \fC< > = != <= >= like\fP operators for comparison and the
|
|
two logical operator \fCand\fP and \fCor\fP, the character \fC%\fP act like a
|
|
wildcard and means: \fI'any sequence of character'\fP.
|
|
|
|
.PP
|
|
Note that the right hand side of the operator must be wrapped in
|
|
quotes.
|
|
|
|
.PP
|
|
After the search is performed a window with the results is shown,
|
|
selecting an item of this window will open the gempub and will add
|
|
all its table of contents on the tour mode, so that the book could
|
|
be browsed.
|
|
|
|
.PP
|
|
For more information on tour mode see below or use
|
|
\fB'C-h A <enter> tour mode'\fP.
|
|
|
|
.SH "Tour mode"
|
|
.PP
|
|
Tinmop maintains a queue of links that can be then visited by the
|
|
user, this queue is called \fBtour\fP.
|
|
|
|
.PP
|
|
There are two ways to add a link to the tour:
|
|
|
|
.IP \(em 4
|
|
when a link window is open and focused pressing \fBt\fP will start a
|
|
prompt for link indices to be saved in the tour; the prompt expect
|
|
a simple, comma or space separated, list of indices or index range, index
|
|
range is a couple of index separated by a dash, example below:
|
|
|
|
.RS
|
|
.nf
|
|
\fC1 2 5 8-12
|
|
\fP
|
|
.fi
|
|
.RE
|
|
|
|
The string above will save the link index number 1, 2, 3, 5, 8, 9,
|
|
10, 11, 12 to the tour.
|
|
|
|
.PP
|
|
The other way to add links to the tour is using the command
|
|
\fB'gemlog-add-unread-posts-tour'\fP (default keychord: \fB'M-g s t a'\fP)
|
|
that will add all the unread posts to the tour.
|
|
|
|
.PP
|
|
There are a few more useful command to manipulate the tour:
|
|
|
|
.TP
|
|
\fBnext-tour-link\fP
|
|
(\fB'M-t t'\fP or just 't' if a gemini window is focused)
|
|
follows the next link in the tour;
|
|
|
|
.TP
|
|
\fBshow-tour-links\fP
|
|
(\fB'M-t s'\fP or just \fB'T'\fP if a gemini window is focused)
|
|
shows the contents of the tour in a link window
|
|
|
|
.TP
|
|
\fBclean-all-tour\fP
|
|
(\fB'M-t c'\fP)
|
|
|
|
.TP
|
|
\fBshuffle-tour \fP
|
|
(\fB'M-t S'\fP) shuffle the contents of the tour
|
|
|
|
.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 uncomment 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.
|