#+TITLE: tinmop * Name tinmop - a client for gemini or pleroma social network * Synopsis tinmop [OPTION]... * Description This document assumes basic knowledge of how fediverse works. More information about this topic can be found on the official website ([[https://docs.joinmastodon.org/]]). Tinmop proposes a terminal interface to connect with Pleroma social network and as client for the gemini protocol gemini://gemini.circumlunar.space/ * Options Without options the program will start a terminal interface and will try to connect to your instance (see [[Configuration]]) + -o, --open-gemini-url ARG :: Open gemini url + -m, --notify-mentions ARG :: Notify messages that mentions the user + -R, --reset-timeline-pagination :: 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 + -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 + -v, --version :: Print program version and exit * Usage Users of Tinmop supposed to interact with the social network using a terminal interface (TUI), The terminal screen layout is sketched below: #+NAME: screen-layout #+BEGIN_SRC text +---------------+---------------------------+ | | | | tags window | thread windows | | | | | | modeline | +---------------+---------------------------+ | | | | conversations | main window | | window | | | | | | | | +---------------+---------------------------+ | command window | +-------------------------------------------+ #+END_SRC 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 [[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 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; - 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 (press tab again to input the next suggestion and so on), otherwise pressing /TAB/ will complete the input with the common prefix of the suggestion window's items; - 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. * Configuration The configuration of tinmop is based on text files but there are available two different kind 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 but user is expected to write a simple file with their credential to log into the server. ** Simple configuration This is a simple file with each entry in a single line that look like this: #+NAME: simple file example #+BEGIN_SRC text # 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 #+END_SRC 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. 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 must be created manually. 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. ** Lisp program 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. 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/~ or ~$HOME/.config/tinmop/~ (because, you know, data is code and code is data) to be successfully loaded. 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 network 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). * How to get more help For help with pleroma visit the pleroma website: https://pleroma.social/ For information about gemini: $ tinmop -o gemini://gemini.circumlunar.space The program has an inline help (default binding for help is "?") You can search the help strings with a command (default: "C-h a"). Moreover you can have some useful hint at the program web page: [https://www.autistici.org/interzona/tinmop/] * BUGS There are many, totally unknown, hiding in the code! Please help the programmer to nail them using the [[https://notabug.org/cage/tinmop/issues/][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 [[https://notabug.org/cage/tinmop/][code repository]]. See also the file CONTRIBUTE.org ** Debug mode If you decomment the line: #+BEGIN_SRC lisp ;;(push :debug-mode *features*) #+END_SRC 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 [[Contributing]]). - ~/etc/tinmop/default-theme.conf~: default visual style - ~/etc/tinmop/shared.conf~: some default configuration not related to themes - ~/etc/tinmop/init.lisp~: system wide configuration - ~$HOME/.config/tinmop/init.lisp~: user configuration - ~$HOME/.config/tinmop/main.conf~: user configuration (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 [[https://beta.quicklisp.org/quicklisp.lisp][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 LINCENSES.org This program is was born also with the help of CCCP: "Collettivo Computer Club Palermo". Also thanks to "barbar" for testing of the installation scripts.