cage/tinmop
1
0
Fork 0
mirror of https://codeberg.org/cage/tinmop/ synced 2024-12-22 23:47:56 +01:00
Code Issues

- updated documentation.

Browse Source
This commit is contained in:
cage 2023-07-30 15:08:21 +02:00
parent dbd211ea2c
commit 85752eb02d
2 changed files with 538 additions and 579 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

818
doc/tinmop.man
View File

File diff suppressed because it is too large Load Diff

299
doc/tinmop.org
View File

@ -10,34 +10,29 @@
* Description * Description
This document assumes basic knowledge of how fediverse works. More This document assumes basic knowledge of how fediverse works. More information about this topic can be found on the following websites:
information about this topic can be found on the following websites:
- [[https://en.wikipedia.org/wiki/Fediverse]] ; - [[https://en.wikipedia.org/wiki/Fediverse]] ;
- [[https://pleroma.social/]] ; - [[https://pleroma.social/]] ;
- [[https://docs.joinmastodon.org/]] . - [[https://docs.joinmastodon.org/]] .
Tinmop proposes an extensible terminal interface to connect with Tinmop proposes an extensible terminal interface to connect with Pleroma social network, the gemini and gopher protocol
Pleroma social network, the gemini and gopher protocol
- gemini://gemini.circumlunar.space/ - gemini://gemini.circumlunar.space/
- [[https://gemini.circumlunar.space/docs/]] - [[https://gemini.circumlunar.space/docs/]]
Finally tinmop can connect to network file system using 9p protocol Finally tinmop can connect to network file system using 9p protocol over TLS (using client certificates as authentication method).
over TLS (using client certificates as authentication method).
For more information about this feature, please visit: For more information about this feature, please visit: [[https://kamid.omarpolo.com/]].
[[https://kamid.omarpolo.com/]].
* Options * Options
Without options the program will start a terminal interface and will Without options the program will start a terminal interface and will try to connect to your instance (see [[Configuration]])
try to connect to your instance (see [[Configuration]])
+ -o, --open-net-address ARG :: Open net address (currentli only gemini or 9p) + -o, --open-net-address ARG :: Open net address (currentli only gemini or 9p)
+ -m, --notify-mentions ARG :: Notify messages that mentions the user + -m, --notify-mentions ARG :: Notify messages that mentions the user
+ -R, --reset-timeline-pagination :: + -R, --reset-timeline-pagination ::
Reset the timeline pagination. By default the new toots are fetched Reset the timeline pagination. By default the new posts are fetched
starting from the last one downloaded from the instance, this switch starting from the last one downloaded from the instance, this switch
will force the program to fetch the last message posted by users will force the program to fetch the last message posted by users
+ -G, --gemini-client-only :: Start as gemini client only + -G, --gemini-client-only :: Start as gemini client only
@ -53,9 +48,8 @@
* Usage * Usage
Users of Tinmop supposed to interact with the social network using a 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
terminal interface (TUI, but starting with version 0.9.9.1414 a GUI for gemini is available See [[GUI]]), The terminal screen layout is sketched
for gemini is available), The terminal screen layout is sketched
below: below:
#+NAME: screen-layout #+NAME: screen-layout
@ -89,7 +83,6 @@
- command window :: the window where the user instruct the software to perform commands - 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: Using the program in gemini exclusive mode (option *"-G"*) the program layout is simplified:
#+NAME: screen-layout-gemini-fullscreen #+NAME: screen-layout-gemini-fullscreen
@ -107,61 +100,41 @@
#+END_SRC #+END_SRC
The main way to interact with the program is using the keyboard. By The main way to interact with the program is using the keyboard. By default you can move focus to each window (except command window
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
that can not get focus explicitly) using *'M-arrow key'* (meta is when the user input data that provide hints about commands and a quick help window that can be shown by hitting ~?~ (if this
*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). keybinding has not been customized).
** Command window keys ** Command window keys
The command window has a few hardcoded command keys to interact The command window has a few hardcoded command keys to interact with it:
with it:
- the *left* and *right* arrow keys move the cursor; - the *left* and *right* arrow keys move the cursor;
- the key *home* and *end* move the cursor to the start and end of - the key *home* and *end* move the cursor to the start and end of the input respectively;
the input respectively; - *canc* and *backspace* delete the next and previous character respectively;
- *canc* and *backspace* delete the next and previous character - the *new line* (often called *enter* key) send the input to the program;
respectively; - *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;
- the *new line* (often called *enter* key) send the input to the - 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;
program; - if suggestions are gemini URI press *TAB* to input the current selected suggestion;
- *C-k* (that is: "press 'control' and while pressed press 'k') - 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.
/kills/ (deletes) the text from the cursor position to the end of
the input previously typed;
- 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 ** Folders
A folder is an object to groups messages for each timeline an 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.
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 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.
* Configuration * Configuration
The configuration of tinmop is based on text files but there are The configuration of tinmop is based on text files but there are available two different kind with different syntax and scope.
available two different kind with different syntax and scope.
- a key-value text files used to configure the access credential to - a key-value text files used to configure the access credential to server and visual theme of the program (simple configuration);
server and visual theme of the program (simple configuration);
- common lisp source code. Used to write module (AKA plugin) and to - common lisp source code. Used to write module (AKA plugin) and to configure keybindings to interact with the software.
configure keybindings to interact with the software.
The distribution of this software comes with a bunch of pre-backed 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.
configuration files but user is expected to write a simple file with
their credential to log into the server.
** Simple configuration ** Simple configuration
@ -183,71 +156,38 @@
#+END_SRC #+END_SRC
Not incidentally the information in the example above are the 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.
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.
As you can see a line starting with a *#* is considered comment and As you can see a line starting with a *#* is considered comment and skipped by the program
skipped by the program
The file with this credential are confidential and must be put into The file with this credential are confidential and must be put into user's home directory under the path
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 must be created manually.
~$HOME/.local/share/tinmop/main.conf~. Probably the directory
~tinmop~ does not exists on user system, if it does not exists must
be created manually.
If the program was installed correctly two other files with simple 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.
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, 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).
the program can be used as gemini client (see the "-G" command line
switch on top of this manual).
** Lisp program ** Lisp program
These files contains Common lisp (see [[https://common-lisp.net/]]) These files contains Common lisp (see [[https://common-lisp.net/]]) source code. And are used both as a way to configure the program and to write module for tinmop itself.
source code. And 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: 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!).
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 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.
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 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/~.
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 However there is no need to write their own init file if user is happy with the provided one by the package maintainers.
happy with the provided one by the package maintainers.
* First time start * First time start
After the configuration the program can be started but we are not 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).
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, There is no additional steps to follow to connect to gemspace, instead.
instead.
* Gempub support * Gempub support
Tinmop maintains a gempub library scanning a directory on your 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:
file system (library directory); the library directory path can be
set using the configuration directive:
#+BEGIN_SRC text #+BEGIN_SRC text
@ -258,9 +198,7 @@
the default value is ~$XDG_DATA_HOME~ (usually something like the default value is ~$XDG_DATA_HOME~ (usually something like
~$HOME/.local/share/tinmop/~). ~$HOME/.local/share/tinmop/~).
Using *'M-g g l'* the library can be inspected using a simple query 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, example of query follows:
language (similar to SQL) that search in the metadata of the gempub
files, example of query follows:
#+BEGIN_SRC text #+BEGIN_SRC text
@ -281,51 +219,35 @@
- published; - published;
- copyright. - copyright.
You can use ~< > = != <= >= like~ operators for comparison and the You can use ~< > = != <= >= like~ operators for comparison and the two logical operator ~and~ and ~or~, the character ~%~ act like a wildcard and means: /'any sequence of character'/.
two logical operator ~and~ and ~or~, the character ~%~ act like a
wildcard and means: /'any sequence of character'/.
Note that the right hand side of the operator must be wrapped in Note that the right hand side of the operator must be wrapped in quotes.
quotes.
After the search is performed a window with the results is shown, 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.
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 For more information on tour mode see below or use *'C-h A <enter> tour mode'*.
*'C-h A <enter> tour mode'*.
* Tour mode * Tour mode
Tinmop maintains a queue of links that can be then visited by the Tinmop maintains a queue of links that can be then visited by the user, this queue is called *tour*.
user, this queue is called *tour*.
There are two ways to add a link to the 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 - 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:
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:
#+BEGIN_SRC text #+BEGIN_SRC text
1 2 5 8-12 1 2 5 8-12
#+END_SRC #+END_SRC
The string above will save the link index number 1, 2, 3, 5, 8, 9, The string above will save the link index number 1, 2, 3, 5, 8, 9, 10, 11, 12 to the tour.
10, 11, 12 to the tour.
The other way to add links to the tour is using the command 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.
*'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: 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) - next-tour-link :: (*'M-t t'* or just 't' if a gemini window is focused) follows the next link in the tour;
follows the next link in the tour;
- show-tour-links :: (*'M-t s'* or just *'T'* if a gemini window is focused) - 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
shows the contents of the tour in a link window
- clean-all-tour :: (*'M-t c'*) - clean-all-tour :: (*'M-t c'*)
@ -341,9 +263,7 @@
$ tinmop -o gemini://gemini.circumlunar.space $ tinmop -o gemini://gemini.circumlunar.space
The program has an inline help (default binding for help is "?"), a 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 can be searched (default: "C-h A").
manpage (default binding to view the manpage is "C-h m") and inline
help can be searched (default: "C-h A").
Moreover you can have some useful hint at the program web page: Moreover you can have some useful hint at the program web page:
@ -353,39 +273,39 @@
** Global keymap ** Global keymap
- ! :: gemini-search - ! :: gemini-search
- > :: open-net-address - > :: open-net-address
- ? :: print-quick-help - ? :: print-quick-help
- C d :: clear-cache - C d :: clear-cache
- C-I :: pass-focus-next - C-I :: pass-focus-next
- C-a :: show-about-window - C-a :: show-about-window
- C-h A :: apropos-help-global - C-h A :: apropos-help-global
- C-h a :: apropos-help - C-h a :: apropos-help
- C-h h :: print-quick-help - C-h h :: print-quick-help
- C-h m :: open-manual - C-h m :: open-manual
- C-q :: quit - C-q :: quit
- M-c :: open-chats-list-window - M-c :: open-chats-list-window
- M-down :: pass-focus-on-bottom - M-down :: pass-focus-on-bottom
- M-e :: eval-command - M-e :: eval-command
- M-g c i :: import-gemini-certificate - M-g c i :: import-gemini-certificate
- M-g c s :: gemini-open-certificates-window - M-g c s :: gemini-open-certificates-window
- M-g g b s :: display-bookmark - M-g g b s :: display-bookmark
- M-g g l :: open-gempub-library - M-g g l :: open-gempub-library
- M-g s o :: gemini-open-gemlog-window - M-g s o :: gemini-open-gemlog-window
- M-g s r :: gemlog-refresh-all - M-g s r :: gemlog-refresh-all
- M-g s t a :: gemlog-add-unread-posts-tour - M-g s t a :: gemlog-add-unread-posts-tour
- M-l :: load-script-file - M-l :: load-script-file
- M-left :: pass-focus-on-left - M-left :: pass-focus-on-left
- M-right :: pass-focus-on-right - M-right :: pass-focus-on-right
- M-s l :: message-window-lock-scrolling - M-s l :: message-window-lock-scrolling
- M-s u :: message-window-unlock-scrolling - M-s u :: message-window-unlock-scrolling
- M-t S :: shuffle-tour - M-t S :: shuffle-tour
- M-t a :: open-gemini-links-and-ask-tour - M-t a :: open-gemini-links-and-ask-tour
- M-t c :: clean-all-tour - M-t c :: clean-all-tour
- M-t s :: show-tour-links - M-t s :: show-tour-links
- M-t t :: next-tour-link - M-t t :: next-tour-link
- M-up :: pass-focus-on-top - M-up :: pass-focus-on-top
- q :: confirm-and-clean-close-program - q :: confirm-and-clean-close-program
** Follow request window ** Follow request window
@ -473,7 +393,6 @@
- x :: refresh-thread - x :: refresh-thread
- | :: send-message-to-pipe - | :: send-message-to-pipe
** Posts window ** Posts window
- / :: message-search-regex - / :: message-search-regex
@ -704,17 +623,13 @@
* BUGS * BUGS
There are many, totally unknown, hiding in the code; this is scary! 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/][issue tracker]].
😱 Please help the programmer to nail them using the
[[https://codeberg.org/cage/tinmop/issues/][issue tracker]].
* Contributing * Contributing
There is always need for help, you can join the developer, sending There is always need for help, you can join the developer, sending patches or translating the UI to your favourite language.
patches or translating the UI to your favourite language.
Just point your browser to the Just point your browser to the [[https://codeberg.org/cage/tinmop/][code repository]].
[[https://codeberg.org/cage/tinmop/][code repository]].
See also the file CONTRIBUTE.org See also the file CONTRIBUTE.org
@ -726,9 +641,7 @@
;;(push :debug-mode *features*) ;;(push :debug-mode *features*)
#+END_SRC #+END_SRC
The program will be compiled in ~debug-mode~ this means that a lot 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/~.
of diagnostic output will be appended to a file named ~tinmop.log~
in the directory ~$HOME/.local/share/tinmop/~.
* Files * Files
@ -737,42 +650,32 @@
- ~$HOME/.local/share/tinmop/tinmop.log~: this file is created only for debugging and should not be enabled in binary package distribution (see [[Contributing]]). - ~$HOME/.local/share/tinmop/tinmop.log~: this file is created only for debugging and should not be enabled in binary package distribution (see [[Contributing]]).
- ~/etc/tinmop/default-theme.conf~: default visual style - ~/etc/tinmop/default-theme.conf~: default visual style
- ~/etc/tinmop/shared.conf~: some default configuration not related to themes - ~/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 - ~/etc/tinmop/init.lisp~: system wide configuration
- ~$HOME/.config/tinmop/init.lisp~: user configuration - ~$HOME/.config/tinmop/init.lisp~: user configuration
- ~$HOME/.config/tinmop/main.conf~: user configuration (simple format) - ~$HOME/.config/tinmop/main.conf~: user configuration (simple format)
- ~$HOME/.config/tinmop/main.conf~: user configuration for GUI (simple format)
* Privacy * Privacy
The author of this software collects no user data information with The author of this software collects no user data information with this software.
this software.
But this software is a client to connect and interact to one or more 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.
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 It is the user responsibility to checks the privacy conditions of the instance this software connect to.
instance this software connect to.
By default, pressing "!" will contact the remote service located at: By default, pressing "!" will contact the remote service located at: "gemini://houston.coder.town/search".
"gemini://houston.coder.town/search".
Moreover launching ~quick_quicklisp.sh~ will contact Moreover launching ~quick_quicklisp.sh~ will contact [[https://www.quicklisp.org/]], check the [[https://beta.quicklisp.org/quicklisp.lisp][quicklisp sources]] for details.
[[https://www.quicklisp.org/]], check the
[[https://beta.quicklisp.org/quicklisp.lisp][quicklisp sources]] for
details.
* Acknowledgment * Acknowledgment
My deep thanks to the folks that provided us with wonderful SBCL and My deep thanks to the folks that provided us with wonderful SBCL and Common lisp libraries.
Common lisp libraries.
In particular i want to thanks the authors of the libraries Croatoan and Tooter In particular i want to thanks the authors of the libraries Croatoan and Tooter for their help when I started to develop this program.
for their help when I started to develop this program.
There are more people i borrowed code and data from, they are mentioned There are more people i borrowed code and data from, they are mentioned in the file LINCENSES.org
in the file LINCENSES.org
This program was born also with the help of CCCP: "Collettivo This program was born also with the help of CCCP: "Collettivo Computer Club Palermo".
Computer Club Palermo".
Also thanks to "barbar" for testing of the installation scripts. Also thanks to "barbar" for testing of the installation scripts.