tinmop/doc/man.org

#+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 an  extensible terminal  interface to  connect with
  Pleroma social network or 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
  + -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
  + -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;
    - 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/~.

   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:

  #+BEGIN_SRC text

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

  #+END_SRC

  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, example of query follows:

  #+BEGIN_SRC text

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

   where author like "cal%" or published = "1980"

  #+END_SRC

  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~,  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
  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:

    #+BEGIN_SRC text
     1 2 5 8-12
    #+END_SRC

    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/

  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 uncomment 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.