tinmop/doc/man.org

#+TITLE: tinmop

* Name
  tinmop - a client for mastodon or pleroma social network

* Synopsis
  tinmop [OPTION]...

* Description

  This document  assumes basic  knowledge of  how mastodon  works. More
  information    about   this    topic   can    be   found    on   the
  official website ([[https://docs.joinmastodon.org/]]).

  Tinmop propose a  terminal interface to to connect  with Mastodon or
  Pleroma social network

* Options
  Without options the program will start a terminal interface and will
  try to connect to your instance (see [[Configuration]])

+ -e, --execute-script SCRIPT-FILE :: Execute a script file
+ -c, --check-follows-requests     :: Checks for follow request at start
+ -u, --update-timeline            :: Update the selected timeline
+ -t, --timeline TIMELINE-NAME     :: Start using this timeline
+ -f, --folder FOLDER-NAME         :: Start on that folder
+ -v, --version                    :: Print program version and exit
+ -h, --help                       :: print program help and exit

* Usage

  Users of  Tinmop supposed  to interacts 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 |      message 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;

  - message window :: show the body of the message selected in the tag window

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

** 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 file can be included in another with this directive:
   use "shared.conf"

   # a line starting with a '#' is a comment
   # The server instance name
   server = server address

   # your username
   username = username

   #+END_SRC

   Not  incidentally  the information  i  the  example above  are  the
   absolute minimum the user has to provide before starts the program:
   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.

** 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 mastodon visit the mastodon website.

  The program has an inline help (default binding for help is "?")

  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/.local/share/tinmop/main.conf~: user configuration (simple format)

* Privacy

  This program do not interact with no other computer other than the
  mastodon instance that the user configured.

  If installed from the source note that the script
 ~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".