cage
/
tinmop
mirror of https://codeberg.org/cage/tinmop/
1
0
Fork 0
Code Issues

- updated docs.

This commit is contained in:
cage 2024-07-11 14:30:51 +02:00
parent 0087e2c363
commit 769e21d840
2 changed files with 100 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
doc/tinmop.man
View File

@ -1,13 +1,10 @@
.TH "tinmop" "1"
.SH "Name"
.PP
tinmop - a client for gemini, gopher, mastodon and pleroma social network and kamid (9p protocol over TLS)
.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 following websites:
@ -32,59 +29,54 @@ Finally tinmop can connect to network file system using 9p protocol over TLS (
.PP
For more information about this feature, please visit: \fIhttps://kamid.omarpolo.com/\fP.
.SH "Options"
.SH "Command line options"
.PP
Without options the program will start a terminal interface and will try to connect to your instance (see \fIConfiguration\fP)
Without options the program will start a terminal interface and will try to connect to your instance (see \fIfuzzy:Configuration\fP), the most useful command line options follows
.TP
\fB-o, --open-net-address ARG \fP
\fB\fC\-o, \-\-open\-net\-address ARG\fP \fP
Open net address (currentli only gemini or 9p)
.TP
\fB-m, --notify-mentions ARG \fP
\fB\fC\-m, \-\-notify\-mentions ARG\fP \fP
Notify messages that mentions the user
.TP
\fB-R, --reset-timeline-pagination \fP
\fB\fC\-R, \-\-reset\-timeline\-pagination\fP \fP
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
.TP
\fB-G, --gemini-client-only \fP
\fB\fC\-G, \-\-gemini\-client\-only\fP \fP
Start as gemini client only
.TP
\fB-c, --check-follows-requests \fP
\fB\fC\-c, \-\-check\-follows\-requests\fP \fP
Checks for follow request at start
.TP
\fB-e, --execute-script SCRIPT-FILE\fP
\fB\fC\-e, \-\-execute\-script SCRIPT\-FILE\fP\fP
Execute a script file
.TP
\fB-f, --folder FOLDER-NAME \fP
Start on that folder
\fB\fC\-f, \-\-folder FOLDER\-NAME\fP \fP
Start on that virtual folder
.TP
\fB-h, --help \fP
\fB\fC\-h, \-\-help\fP \fP
print program help and exit
.TP
\fB-t, --timeline TIMELINE-NAME \fP
\fB\fC\-t, \-\-timeline TIMELINE\-NAME\fP \fP
Start using this timeline
.TP
\fB-u, --update-timeline \fP
\fB\fC\-u, \-\-update\-timeline\fP \fP
Update the selected timeline
.TP
\fB-U, --gemini-gui-client-only \fP
\fB\fC\-U, \-\-gemini\-gui\-client\-only\fP \fP
Start the program as A gemini GUI client
.TP
\fB-S, --gemini-gui-server-only \fP
Start as gemini gui server only
.TP
\fB-v, --version \fP
\fB\fC\-v, \-\-version\fP \fP
Print program version and exit
.TP
\fB-F, --fediverse-account \fP
\fB\fC\-F, \-\-fediverse\-account\fP \fP
Specify a fediverse user account (format: user-name@server-name)
.SH "Usage"
.PP
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 \fIGUI\fP), the terminal screen layout is sketched below:
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 \fIfuzzy:GUI\fP), the terminal screen layout is sketched below:
.RS
.nf
@ -116,7 +108,7 @@ 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;
for a given timeline and folder (see \fIfuzzy:Folders\fP) show the discussions saved in user's local database;
.TP
\fBconversations window\fP
@ -152,7 +144,6 @@ Using the program in gemini exclusive mode (option \fB"-G"\fP) the program layou
.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:
@ -175,18 +166,15 @@ press \fBM-left\fP and \fBM-right\fP (\fBleft alt\fP and \fBleft\fP or \fBright\
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.
.SS "GUI"
.PP
Calling this program with option \fB"-U"\fP will starts with a gemini client with a GUI mode. The Usage should be intuitive for persons that are used to program with a graphical interface and mouse interaction. Note that currently gempub files are not supported by GUI. Other features (like tour mode), are though.
Calling this program with option \fB"-U"\fP 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.
.SH "Configuration"
.PP
The configuration of tinmop is based on text files but there are available two different kind with different syntax and scope.
The configuration of tinmop is based on text files but they are available two different kinds with different syntax and scope.
.IP \(em 4
a key-value text files used to configure the access credential to server and visual theme of the program (simple configuration);
@ -196,11 +184,10 @@ common lisp source code. Used to write module (AKA plugin) and to configure keyb
.PP
The distribution of this software comes with a bunch of pre-backed configuration files
(see \fIFiles\fP) 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.
(see \fIfuzzy:Files\fP) 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.
.PP
The system wide configuration files are automatically included in user defined files, the configuration directive in custom files override the system wide ones.
.SS "Simple configuration"
.PP
This is a simple file with each entry in a single line that look like this:
@ -238,7 +225,6 @@ If the program was installed correctly two other files with simple semantics are
.PP
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).
.SS "Lisp program"
.PP
These files contains Common lisp (see \fIhttps://common-lisp.net/\fP) source code. They are used both as a way to configure the program and to write module for tinmop itself.
@ -254,14 +240,12 @@ Again in the configuration directory there is a (commented) file named \fCinit.l
.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:
@ -337,7 +321,6 @@ After the search is performed a window with the results is shown, selecting an i
.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.
@ -379,7 +362,6 @@ There are a few more useful command to manipulate the tour:
.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:
@ -407,7 +389,6 @@ Moreover you can have some useful hint at the program web page:
.PP
\fIhttps://www.autistici.org/interzona/tinmop/\fP
.SH "Default keybindings for TUI"
.SS "Global keymap"
.TP
@ -515,7 +496,6 @@ pass-focus-on-top
.TP
\fBq \fP
confirm-and-clean-close-program
.SS "Follow request window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -538,7 +518,6 @@ cancel-follow-requests
.TP
\fBup \fP
follow-request-go-up
.SS "Send post window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -565,6 +544,9 @@ change-mentions
\fBq \fP
cancel-send-message
.TP
\fBC-g \fP
cancel-send-message
.TP
\fBs \fP
change-subject
.TP
@ -573,7 +555,6 @@ attach-go-up
.TP
\fBv \fP
change-visibility
.SS "Thread window"
.TP
\fB[ \fP
@ -582,18 +563,18 @@ thread-go-to-parent-post
\fB^ \fP
thread-open-parent-post
.TP
\fB/ q \fP
search-fediverse
.TP
\fB/ Q \fP
search-fediverse-local (see: \fIfuzzy:Fediverse local search\fP)
.TP
\fB/ b \fP
thread-search-next-message-body
.TP
\fB/ m \fP
thread-search-next-message-meta
.TP
\fB/ q \fP
search-fediverse
.TP
\fB/ Q \fP
search-fediverse-local (see: \fIFediverse local search\fP)
.TP
\fBC-J (key \fIenter\fP)\fP
thread-open-selected-message
.TP
@ -693,6 +674,9 @@ delete-notifications
\fBT d \fP
thread-delete-subtree
.TP
\fBe \fP
edit-posted-message
.TP
\fBP \fP
poll-vote
.TP
@ -770,7 +754,6 @@ refresh-thread
.TP
\fB| \fP
send-message-to-pipe
.SS "Fediverse local search"
.PP
The database containing posts fetched from the server can be searched using a simple query language (loosely similar to SQL):
@ -863,7 +846,6 @@ Note that the right hand side of the operator must be wrapped in quotes.
.PP
The results are saved in the folder specified after the clause \fIinto\fP (if omitted a default folder name is used), note that the folder name can not contains spaces.
.SS "Posts window"
.TP
\fB/ \fP
@ -916,7 +898,6 @@ message-scroll-up
.TP
\fB| \fP
send-to-pipe
.SS "Gemini viewer window"
.TP
\fB/ \fP
@ -1023,7 +1004,6 @@ message-scroll-up
.TP
\fB| \fP
send-to-pipe
.SS "Gemini page table of contents window"
.TP
\fB/ \fP
@ -1059,9 +1039,11 @@ gemini-toc-scroll-up-page
\fBq \fP
gemini-toc-close
.TP
\fBC-g \fP
gemini-toc-close
.TP
\fBup \fP
gemini-toc-scroll-up
.SS "Gemini stream window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1084,7 +1066,6 @@ gemini-streams-window-close
.TP
\fBup \fP
gemini-streams-window-up
.SS "Gemini certificates window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1105,6 +1086,9 @@ gemini-certificate-window-go-up
\fBq \fP
gemini-close-certificate-window
.TP
\fBC-g \fP
gemini-close-certificate-window
.TP
\fBup \fP
gemini-certificate-window-go-up
.TP
@ -1113,7 +1097,6 @@ gemini-change-certificate-password
.TP
\fBD \fP
clear-cached-client-tls-certificates
.SS "Gemini subscription window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1137,9 +1120,11 @@ open-message-link
\fBq \fP
close-gemlog-window
.TP
\fBC-g \fP
close-gemlog-window
.TP
\fBup \fP
gemlogs-subscription-go-up
.SS "Gempub library window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1157,9 +1142,11 @@ gempub-library-window-go-up
\fBq \fP
gempub-library-window-close
.TP
\fBC-g \fP
gempub-library-window-close
.TP
\fBup \fP
gempub-library-window-go-up
.SS "Post's tag window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1185,7 +1172,6 @@ subscribe-to-hash
.TP
\fBup \fP
tag-go-up
.SS "Conversations window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1211,12 +1197,14 @@ conversation-go-up
.TP
\fBup \fP
conversation-go-up
.SS "Attachments window"
.TP
\fBC-J (key \fIenter\fP) \fP
open-message-attach-perform-opening
.TP
\fBO \fP
open-attachment-ignoring-cache
.TP
\fBC-c \fP
copy-from-attach-window-to-clipboard
.TP
@ -1235,9 +1223,11 @@ open-message-attach-go-up
\fBq \fP
close-open-attach-window
.TP
\fBC-g \fP
close-open-attach-window
.TP
\fBup \fP
open-message-attach-go-up
.SS "Links window"
.TP
\fB/ \fP
@ -1276,12 +1266,14 @@ open-message-link-go-up
\fBq \fP
close-open-message-link-window
.TP
\fBC-g \fP
close-open-message-link-window
.TP
\fBt \fP
tour-mode-link
.TP
\fBup \fP
open-message-link-go-up
.SS "Chats list window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1308,12 +1300,14 @@ change-chat-label
\fBq \fP
close-chats-list-window
.TP
\fBC-g \fP
close-chats-list-window
.TP
\fBr \fP
refresh-chat-messages
.TP
\fBup \fP
chat-list-go-up
.SS "Chat window"
.TP
\fB/ \fP
@ -1348,7 +1342,6 @@ message-scroll-previous-page
.TP
\fBup \fP
message-scroll-up
.SS "File explorer"
.TP
\fB/ \fP
@ -1411,6 +1404,9 @@ file-explorer-mark-entry
\fBq \fP
file-explorer-close-window
.TP
\fBC-g \fP
file-explorer-close-window
.TP
\fBr \fP
file-explorer-rename-path
.TP
@ -1422,7 +1418,6 @@ file-explorer-go-up
.TP
\fBx \fP
file-explorer-expand-path
.SS "Gopher window"
.TP
\fBC-J (key \fIenter\fP) \fP
@ -1451,11 +1446,9 @@ gopher-window:go-to-previous-link
.TP
\fBup \fP
gopher-window:go-to-previous-link
.SH "BUGS"
.PP
There are many, totally unknown, hiding in the code; this is scary! 😱 Please help the programmer to nail them using the https://codeberg.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 https://translate.codeberg.org/engage/tinmop/ \fBat\fP \fItranslating the UI\fP to your favourite language.
@ -1465,7 +1458,6 @@ Just point your browser to the https://codeberg.org/cage/tinmop/ \fBat\fP \fIcod
.PP
See also the file CONTRIBUTE.org
.SS "Debug mode"
.PP
If you uncomment the line:
@ -1479,14 +1471,13 @@ If you uncomment the line:
.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).
\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 \fIfuzzy:Contributing\fP).
.IP \(em 4
\fC/etc/tinmop/default\-theme.conf\fP: default visual style
.IP \(em 4
@ -1501,7 +1492,6 @@ The program will be compiled in \fCdebug\-mode\fP this means that a lot of diagn
\fC$HOME/.config/tinmop/main.conf\fP: user configuration (simple format)
.IP \(em 4
\fC$HOME/.config/tinmop/main.conf\fP: user configuration for GUI (simple format)
.SH "Privacy"
.PP
The author of this software collects no user data information with this software.
@ -1517,7 +1507,6 @@ By default, pressing "!" will contact the remote service located at: "gemini://h
.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.

60
doc/tinmop.org
View File

@ -18,34 +18,41 @@
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.
- [[gemini://geminiprotocol.net/docs/]]
-
#+BEGIN_EXPORT html
<a href="gemini://geminiprotocol.net/docs/">
gemini://geminiprotocol.net/docs/
</a>
#+END_EXPORT
#+BEGIN_EXPORT man
\fIgemini://geminiprotocol.net/docs/\fP
#+END_EXPORT
- [[https://geminiprotocol.net/docs/]]
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/]].
* Options
* Command line options
Without options the program will start a terminal interface and will try to connect to your instance (see [[Configuration]])
Without options the program will start a terminal interface and will try to connect to your instance (see [[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 ::
+ ~-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 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
+ -S, --gemini-gui-server-only :: Start as gemini gui server only
+ -v, --version :: Print program version and exit
+ -F, --fediverse-account :: Specify a fediverse user account (format: user-name@server-name)
+ ~-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
@ -121,11 +128,11 @@
** 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 program with a graphical interface and mouse interaction. Note that currently gempub files are not supported by GUI. Other features (like tour mode), are though.
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 there are available two different kind with different syntax and scope.
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);
@ -342,6 +349,7 @@
- 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
@ -350,10 +358,10 @@
- [ :: thread-go-to-parent-post
- ^ :: thread-open-parent-post
- / b :: thread-search-next-message-body
- / m :: thread-search-next-message-meta
- / q :: search-fediverse
- / Q :: search-fediverse-local (see: [[Fediverse local search]])
- / 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
@ -387,6 +395,7 @@
- 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
@ -544,6 +553,7 @@
- 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
@ -564,6 +574,7 @@
- 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
@ -577,6 +588,7 @@
- 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
@ -586,6 +598,7 @@
- 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
@ -613,12 +626,14 @@
** 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
@ -635,6 +650,7 @@
- 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
@ -648,6 +664,7 @@
- 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
@ -687,6 +704,7 @@
- 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