cage/tinmop
1
0
Fork 0
mirror of https://codeberg.org/cage/tinmop/ synced 2024-12-27 00:12:31 +01:00
Code Issues
8d2553c4ec
tinmop/doc/tinmop.org
cage b76f6bda1b - [GUI] added initial support for gempub; 
- [DOC] fixed syntax of query language for searching in gempub library.
2024-09-14 17:41:29 +02:00

30 KiB
Raw Blame History

tinmop

Name

tinmop - a client for gemini, gopher, mastodon and pleroma social network and kamid (9p protocol over TLS)

Synopsis

tinmop [OPTION]…

Description

This document assumes basic knowledge of how fediverse works. More information about this topic can be found on the following websites:

Tinmop proposes an extensible terminal interface to connect with Mastodon or Pleroma social network, the gemini (for connecting to gemspace an optional graphical interface is also available) and gopher protocol.

Finally tinmop can connect to network file system using 9p protocol over TLS (using client certificates as authentication method).

For more information about this feature, please visit: https://kamid.omarpolo.com/.

Command line options

Without options the program will start a terminal interface and will try to connect to your instance (see /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/Configuration), the most useful command line options follows

-o, --open-net-address ARG
Open net address (currentli only gemini or 9p)
-m, --notify-mentions ARG
Notify messages that mentions the user
-R, --reset-timeline-pagination
Reset the timeline pagination. By default the new posts 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
-G, --gemini-client-only
Start as gemini client only
-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 virtual folder
-h, --help
print program help and exit
-t, --timeline TIMELINE-NAME
Start using this timeline
-u, --update-timeline
Update the selected timeline
-U, --gemini-gui-client-only
Start the program as A gemini GUI client
-v, --version
Print program version and exit
-F, --fediverse-account
Specify a fediverse user account (format: user-name@server-name)

Usage

Users of Tinmop supposed to interact with the social network using a terminal interface (TUI, but starting with version 0.9.9.1414 a GUI for gemini is available See /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/GUI), the terminal screen layout is sketched below:

   +---------------+---------------------------+
   |               |                           |
   | tags window   |      thread windows       |
   |               |                           |
   |               |  modeline                 |
   +---------------+---------------------------+
   |               |                           |
   | conversations |      main window          |
   |    window     |                           |
   |               |                           |
   |               |                           |
   +---------------+---------------------------+
   |              command window               |
   +-------------------------------------------+

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 /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/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

Using the program in gemini exclusive mode (option "-G") the program layout is simplified:

   +------------------------------------------+
   |                                          |
   |               main window                |
   |                                          |
   |                                          |
   |                                          |
   +------------------------------------------+
   |              command window              |
   +------------------------------------------+

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 'M-arrow key' (meta is ALT 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 ? (if this keybinding has not been customized).

Command window keys

The command window has a few hardcoded command keys to interact with it:

  • the left and right arrow keys move the cursor;
  • the key home and end move the cursor to the start and end of the input respectively;
  • canc and backspace delete the next and previous character respectively;
  • the new line (often called enter key) send the input to the program;
  • C-k (that is: "press 'control' and while pressed press 'k') kills (deletes) the text from the cursor position to the end of the input previously typed;
  • C-g will cancel the prompt and quit the command;
  • press M-left and M-right (left alt and left or right 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;
  • if suggestions are gemini URI press TAB to input the current selected suggestion;
  • if suggestion window is not rendered, pressing up and down arrow keys will cycle through input history, if there is not a suggestion window rendered pressing up and down will scroll on suggestions.

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.

GUI

Calling this program with option "-U" will starts with a gemini client with a GUI mode. The Usage should be intuitive for persons that are used to use programs with a graphical interface and mouse interaction. Note that currently gempub files are not supported by GUI. Other features (like tour mode) are, though.

Configuration

The configuration of tinmop is based on text files but they are available two different kinds 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 (see /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/Files) but user is expected to write a simple file with their credential to log into the server, if you want to use tinmop as a fediverse client.

The system wide configuration files are automatically included in user defined files, the configuration directive in custom files override the system wide ones.

Simple configuration

This is a simple file with each entry in a single line that look like this:

# 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

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/mastodon (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 will be created by the software the first time it will run.

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.

Is worth mentioning again that, without an user configuration file, the program can be used as gemini client (see the "-G" command line switch on top of this manual).

Lisp program

These files contains Common lisp (see https://common-lisp.net/) source code. They 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/.

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 fediverse 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).

There is no additional steps to follow to connect to gemspace, instead.

Gempub support

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:

 gempub.directory.library = /absolute/path/to/your/gempub/library

the default value is $XDG_DATA_HOME (usually something like $HOME/.local/share/tinmop/).

Using 'M-g g l' the library can be inspected using a simple query language (similar to SQL) that search in the metadata of the gempub files:

  *where* criteria

for example:

 where author like "calvino" and published < "1980"

 where author like "c%al" or published = "1980"

Valid search keys are:

  • title;
  • author;
  • language;
  • description;
  • publish-date;
  • revision-date;
  • published;
  • copyright.

You can use < > = != <= >= like operators for comparison and the two logical operator and and or; in the case of the like operator the character % act like a wildcard and means: 'any sequence of character'. A % is implicitly added at both the ends of the string, that is like "foo" will match any string that contains "foo".

Note that the right hand side of the operator must be wrapped in quotes.

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.

For more information on tour mode see below or use 'C-h A <enter> tour mode'.

Tour mode

Tinmop maintains a queue of links that can be then visited by the user, this queue is called tour.

There are two ways to add a link to the tour:

  • when a link window is open and focused pressing t 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:
 1 2 5 8-12

The string above will save the link index number 1, 2, 3, 5, 8, 9, 10, 11, 12 to the tour.

The other way to add links to the tour is using the command 'gemlog-add-unread-posts-tour' (default keychord: 'M-g s t a') that will add all the unread posts to the tour.

There are a few more useful command to manipulate the tour:

next-tour-link
('M-t t' or just 't' if a gemini window is focused) follows the next link in the tour;
show-tour-links
('M-t s' or just 'T' if a gemini window is focused) shows the contents of the tour in a link window
clean-all-tour
('M-t c')
shuffle-tour
('M-t S') shuffle the contents of the tour

How to get more help

For help with pleroma visit the pleroma website:

https://pleroma.social/

The mastodon website can be found at:

https://joinmastodon.org/

For information about gemini:

$ tinmop -o gemini://geminiprotocol.net/

The program has an inline help (default binding for help is "?"), a manpage (default binding to view the manpage is "C-h m") and inline help that can be searched (default: "C-h A").

Moreover you can have some useful hint at the program web page:

https://www.autistici.org/interzona/tinmop/

Default keybindings for TUI

Global keymap

!
gemini-search
>
open-net-address
@
switch-fediverse-account
?
print-quick-help
C d
clear-cache
C-I
pass-focus-next
C-a
show-about-window
A
show-announcements
C-h A
apropos-help-global
C-h a
apropos-help
C-h h
print-quick-help
C-h m
open-manual
C-q
quit
M-c
open-chats-list-window
M-down
pass-focus-on-bottom
M-e
eval-command
M-g c i
import-gemini-certificate
M-g c s
gemini-open-certificates-window
M-g g b s
display-bookmark
M-g g l
open-gempub-library
M-g s o
gemini-open-gemlog-window
M-g s r
gemlog-refresh-all
M-g s t a
gemlog-add-unread-posts-tour
M-l
load-script-file
M-left
pass-focus-on-left
M-right
pass-focus-on-right
M-s l
message-window-lock-scrolling
M-s u
message-window-unlock-scrolling
M-t S
shuffle-tour
M-t a
open-gemini-links-and-ask-tour
M-t c
clean-all-tour
M-t s
show-tour-links
M-t t
next-tour-link
M-up
pass-focus-on-top
q
confirm-and-clean-close-program

Follow request window

C-J (key enter)
process-follow-requests
d
follow-request-delete
down
follow-request-go-down
j
follow-request-go-down
k
follow-request-go-up
q
cancel-follow-requests
up
follow-request-go-up

Send post window

C-J (key enter)
send-message
d
attach-delete
down
attach-go-down
e
edit-message-body
j
attach-go-down
k
attach-go-up
m
change-mentions
q
cancel-send-message
C-g
cancel-send-message
s
change-subject
up
attach-go-up
v
change-visibility

Thread window

[
thread-go-to-parent-post
^
thread-open-parent-post
/ q
search-fediverse
/ Q
search-fediverse-local (see: /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/Fediverse%20local%20search)
/ b
thread-search-next-message-body
/ m
thread-search-next-message-meta
C-J (key enter)
thread-open-selected-message
C-X m b
boost-selected-status
C-X m f
favourite-selected-status
C-X m r b
unboost-selected-status
C-X m r f
unfavourite-selected-status
C-X m s
subscribe-to-hash
C-X m t
move-message-tree
C-X m u
unsubscribe-to-hash
C-c c
change-conversation-name
C-c o
open-conversation
C-c u
update-conversations
C-f c
change-folder
C-t R
reset-timeline-pagination
C-t U
update-current-timeline-backwards
C-t c
change-timeline
C-t h r
refresh-tags
C-t u
update-current-timeline
C-u c k g
crypto-generate-key
C-u c k i
crypto-import-key
C-u c k s
crypto-export-key
C-u f
follow-user
C-u i
ignore-user
C-u r f
start-follow-request-processing
C-u r r
report-status
C-u u
unfollow-user
C-u v a
view-user-avatar
C-u x
unignore-user
D
delete-post-using-regex
I
print-post-id
M
print-mentions
M-u
delete-and-move-previous
N d
delete-notifications
T d
thread-delete-subtree
e
edit-posted-message
P
poll-vote
p
show-parent-post
U
thread-mark-prevent-delete-selected-message
X
refresh-thread-totally
\\ \\
repeat-search
\\ b
thread-search-previous-message-body
\\ m
thread-search-previous-message-meta
c
compose-message
d
delete-and-move-next
dc (key delete)
thread-mark-delete-selected-message
down
thread-go-down
end
thread-goto-last-message
g
thread-goto-message
home
thread-goto-first-message
j
thread-go-down
k
thread-go-up
l
open-message-link
left
open-previous
n
thread-search-next-unread-message
r
reply-message
right
open-next
s d
status-tree->text
up
thread-go-up
v
open-message-attach
x
refresh-thread
|
send-message-to-pipe

Fediverse local search

The database containing posts fetched from the server can be searched using a simple query language (loosely similar to SQL):

  *where* criteria [*into* folder-name]

examples:

  where rendered-text like "calvino" and username like "cage" into writer-review

  where rendered-text like "calvino" and (username like "cage" or rebblogged =1)

Valid search keys are:

  • account-id;
  • account;
  • application;
  • content; This columns holds the original content of the post in HTML format;
  • favourited;
  • favourites-count;
  • folder;
  • language;
  • muted; Boolean value: 0 or 1;
  • reblogged;
  • reblogs-count;
  • redp;
  • rendered-text; This columns holds the content of the post as displayed on the program window;
  • replies-count;
  • sensitive; Boolean value: 0 or 1;
  • spoiler-text;
  • status-id;
  • tags;
  • timeline;
  • uri; the address of the post in JSON format
  • url; The internet address of the HTML representation of the post;
  • username;
  • visibility.

You can use < > = != <= >= like operators for comparison and the two logical operator and and or; in the case of the like operator the character % act like a wildcard and means: 'any sequence of character'. A % is implicitly added at both the ends of the string, that is like "foo" will became "%foo%" and will matches any string that contains "foo".

Note that the right hand side of the operator must be wrapped in quotes.

The results are saved in the folder specified after the clause into (if omitted a default folder name is used), note that the folder name can not contains spaces.

Posts window

/
message-search-regex
C-J (key enter)
message-scroll-down
N
repeat-search
b
net-address-history-back
d
delete-shown-post
down
message-scroll-down
end
message-scroll-end
home
message-scroll-begin
j
message-scroll-down
k
message-scroll-up
l
message-extract-links
left
message-scroll-left
npage
message-scroll-next-page
ppage
message-scroll-previous-page
right
message-scroll-right
up
message-scroll-up
|
send-to-pipe

Gemini viewer window

/
message-search-regex
B
address-go-back-in-path
C-J (key enter)
message-scroll-down
C-[
go-to-previous-link
C-]
go-to-next-link
C-b a
bookmark-gemini-page
C-b d
delete-gemini-bookmark
C-b s
display-bookmark
I M
gemini-images-montage
N
repeat-search
O
open-gemini-toc
R
address-go-root-path
T
show-tour-links
U
gemini-view-source
[
open-previous-link
]
open-next-visible-link
b
net-address-history-back
c
gemini-open-certificates-window
d
gemini-open-streams-window
down
message-scroll-down
end
message-scroll-end
home
message-scroll-begin
j
message-scroll-down
k
message-scroll-up
l
open-message-link
left
message-scroll-left
npage
message-scroll-next-page
p
message-toggle-preformatted-block
ppage
message-scroll-previous-page
r
gemini-refresh-page
right
message-scroll-right
s
gemini-subscribe-gemlog
t
next-tour-link
up
message-scroll-up
|
send-to-pipe

Gemini page table of contents window

/
gemini-toc-search
C-J (key enter)
gemini-toc-scroll-down-page
N
repeat-search
down
gemini-toc-scroll-down
end
gemini-toc-scroll-end
home
gemini-toc-scroll-begin
j
gemini-toc-scroll-down
k
gemini-toc-scroll-up
n
gemini-toc-scroll-down-page
p
gemini-toc-scroll-up-page
q
gemini-toc-close
C-g
gemini-toc-close
up
gemini-toc-scroll-up

Gemini stream window

C-J (key enter)
gemini-streams-window-open-stream
a
gemini-abort-download
down
gemini-streams-window-down
j
gemini-streams-window-down
k
gemini-streams-window-up
q
gemini-streams-window-close
up
gemini-streams-window-up

Gemini certificates window

C-J (key enter)
gemini-certificate-information
d
gemini-delete-certificate
down
gemini-certificate-window-go-down
j
gemini-certificate-window-go-down
k
gemini-certificate-window-go-up
q
gemini-close-certificate-window
C-g
gemini-close-certificate-window
up
gemini-certificate-window-go-up
c
gemini-change-certificate-password
D
clear-cached-client-tls-certificates

Gemini subscription window

C-J (key enter)
show-gemlog-to-screen
d
gemlog-cancel-subscription
down
gemlogs-subscription-go-down
j
gemlogs-subscription-go-down
k
gemlogs-subscription-go-up
l
open-message-link
q
close-gemlog-window
C-g
close-gemlog-window
up
gemlogs-subscription-go-up

Gempub library window

C-J (key enter)
gempub-open-file
down
gempub-library-window-go-down
j
gempub-library-window-go-down
k
gempub-library-window-go-up
q
gempub-library-window-close
C-g
gempub-library-window-close
up
gempub-library-window-go-up

Post's tag window

C-J (key enter)
open-tag-folder
U
unsubscribe-to-hash
down
tag-go-down
j
tag-go-down
k
tag-go-up
r
refresh-tags
s
subscribe-to-hash
up
tag-go-up

Conversations window

C-J (key enter)
goto-conversation
C-c c
change-conversation-name
I
ignore-conversation
dc (key delete)
delete-conversation
down
conversation-go-down
j
conversation-go-down
k
conversation-go-up
up
conversation-go-up

Attachments window

C-J (key enter)
open-message-attach-perform-opening
O
open-attachment-ignoring-cache
C-c
copy-from-attach-window-to-clipboard
a
open-all-message-attachments
down
open-message-attach-go-down
j
open-message-attach-go-down
k
open-message-attach-go-up
q
close-open-attach-window
C-g
close-open-attach-window
up
open-message-attach-go-up

Links window

/
search-link-window
C-c
copy-from-message-link-to-clipboard
N
repeat-search
T
save-selected-message-in-tour
]
gemini-jump-to-link
down
open-message-link-go-down
e
open-message-link-open-enqueue
end
open-message-link-window-scroll-end
home
open-message-link-window-scroll-begin
j
open-message-link-go-down
k
open-message-link-go-up
q
close-open-message-link-window
C-g
close-open-message-link-window
t
tour-mode-link
up
open-message-link-go-up

Chats list window

C-J (key enter)
show-chat-to-screen
R
refresh-chats
c
chat-create-new
down
chat-list-go-down
j
chat-list-go-down
k
chat-list-go-up
l
change-chat-label
q
close-chats-list-window
C-g
close-chats-list-window
r
refresh-chat-messages
up
chat-list-go-up

Chat window

/
message-search-regex
M-c
write-to-chat
a
open-chat-link-window
down
message-scroll-down
end
message-scroll-end
home
message-scroll-begin
j
message-scroll-down
k
message-scroll-up
npage
message-scroll-next-page
ppage
message-scroll-previous-page
up
message-scroll-up

File explorer

/
file-explorer-search
C-J (key enter)
file-explorer-open-node
D
file-explorer-delete-tree
M d
file-explorer-download-mirror
M u
file-explorer-upload-mirror
M-m
file-explorer-mark-by-regexp
N
repeat-search
X
file-explorer-delete-marked
a
file-explorer-create-path
c
file-explorer-close-path
d
file-explorer-download-path
down
file-explorer-go-down
e
file-explorer-edit-file
end
file-explorer-scroll-end
home
file-explorer-scroll-begin
i
file-explorer-node-details
j
file-explorer-go-down
k
file-explorer-go-up
m
file-explorer-mark-entry
q
file-explorer-close-window
C-g
file-explorer-close-window
r
file-explorer-rename-path
u
file-explorer-upload-path
up
file-explorer-go-up
x
file-explorer-expand-path

Gopher window

C-J (key enter)
gopher-window:open-menu-link
C-b a
bookmark-gopher-page
C-b d
delete-gemini-bookmark
C-b s
display-bookmark
b
net-address-history-back
down
gopher-window:go-to-next-link
j
gopher-window:go-to-next-link
k
gopher-window:go-to-previous-link
up
gopher-window:go-to-previous-link

BUGS

There are many, totally unknown, hiding in the code; this is scary! 😱 Please help the programmer to nail them using the 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 code repository.

See also the file CONTRIBUTE.org

Debug mode

If you uncomment the line:

;;(push :debug-mode *features*)

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 /cage/tinmop/src/commit/8d2553c4ec08b1861c091de87d110d08c11d1bce/doc/Contributing).
  • /etc/tinmop/default-theme.conf: default visual style
  • /etc/tinmop/shared.conf: some default configuration not related to themes
  • /etc/tinmop/shared-gui.conf: default configuration for GUI
  • /etc/tinmop/init.lisp: system wide configuration
  • $HOME/.config/tinmop/init.lisp: user configuration
  • $HOME/.config/tinmop/main.conf: user configuration (simple format)
  • $HOME/.config/tinmop/main.conf: user configuration for GUI (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 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 LICENSES.org

This program was born also with the help of CCCP: "Collettivo Computer Club Palermo".

Also thanks to "barbar" for testing of the installation scripts.