cage/tinmop
1
0
Fork 0
mirror of https://codeberg.org/cage/tinmop/ synced 2025-02-20 08:40:36 +01:00
Code Issues

- always load a shared configuration file;

Browse Source 
- updated documentation.
This commit is contained in:
cage 2020-05-16 13:45:07 +02:00
parent b1a2023738
commit 149b39e93b
5 changed files with 127 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
doc/man.org
View File

@ -8,29 +8,29 @@
* Description
This document assumes basic knowledge of how mastodon works. More
information about this topic can be found on the
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
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
+ -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
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
@ -54,11 +54,11 @@
The screen is subdivided in five window:
- tag window :: shows the tag users subscribed for and available
messages for each tag;
- 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;
- 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;
@ -66,30 +66,30 @@
- 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
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 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
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);
- 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.
- 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
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.
@ -100,10 +100,11 @@
#+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
# a file can be included in another with this directive:
# use "shared.conf"
# The server instance name
server = server address
@ -112,58 +113,58 @@
#+END_SRC
Not incidentally the information i 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:
the name you chose when you made the account on the server and the
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
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
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
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
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
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
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
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
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
@ -207,9 +208,9 @@
- ~$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]]).
- ~$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/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)
@ -236,5 +237,5 @@
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
This program is was born also with the help of CCCP: "Collettivo Computer
Club Palermo".

107
doc/tinmop.man
View File

@ -10,12 +10,12 @@ tinmop [OPTION]...
.SH "Description"
.PP
This document assumes basic knowledge of how mastodon works. More
information about this topic can be found on the
This document assumes basic knowledge of how mastodon works. More
information about this topic can be found on the
official website (\fIhttps://docs.joinmastodon.org/\fP).
.PP
Tinmop propose a terminal interface to to connect with Mastodon or
Tinmop propose a terminal interface to to connect with Mastodon or
Pleroma social network
.SH "Options"
@ -47,8 +47,8 @@ print program help and exit
.SH "Usage"
.PP
Users of Tinmop supposed to interacts with the social network
using a terminal interface (TUI), The terminal screen layout is
Users of Tinmop supposed to interacts with the social network
using a terminal interface (TUI), The terminal screen layout is
sketched below:
.RS
@ -76,13 +76,15 @@ sketched below:
The screen is subdivided in five window:
.TP
\fBtag window \fP
shows the tag users subscribed for and available
\fBtag window\fP
shows the tag users subscribed for and available
.PP
messages for each tag;
.TP
\fBthreads window \fP
for a given timeline and folder (see
\fBthreads window\fP
for a given timeline and folder (see
.PP
\fIFolders\fP) show the discussions saved in user's local database;
.TP
@ -98,33 +100,35 @@ show the body of the message selected in the tag window
the window where the user instruct the software to perform commands
.PP
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 \fC?\fP (if this keybinding has not been
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 \fC?\fP (if this keybinding has not been
customized).
.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 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.
.SH "Configuration"
.PP
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.
.IP \(em 4
a key-value text files used to configure the access credential to
a key-value text files used to configure the access credential to
.PP
server and visual theme of the program (simple configuration);
.IP \(em 4
common lisp source code. Used to write module (AKA plugin) and to
common lisp source code. Used to write module (AKA plugin) and to
.PP
configure keybindings to interact with the software.
.PP
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.
@ -135,10 +139,11 @@ This is a simple file with each entry in a single line that look like this:
.RS
.nf
\fC
# a file can be included in another with this directive:
use "shared.conf"
# 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
@ -150,9 +155,9 @@ username = username
.RE
.PP
Not incidentally the information i 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:
the name you chose when you made the account on the server and the
the name you chose when you made the account on the server and the
address of the server.
.PP
@ -161,54 +166,54 @@ skipped by the program
.PP
The file with this credential are confidential and must be put into
user's home directory under the path
\fC$HOME/.local/share/tinmop/main.conf\fP. Probably the directory
user's home directory under the path
\fC$HOME/.local/share/tinmop/main.conf\fP. Probably the directory
\fCtinmop\fP does not exists on user system, if it does not exists must
be created manually.
.PP
If the program was installed correctly two other files with simple
semantics are located in your system wide configuration directory
(usually \fC/etc/tinmop/\fP), please check these files for more
If the program was installed correctly two other files with simple
semantics are located in your system wide configuration directory
(usually \fC/etc/tinmop/\fP), please check these files for more
information, as they are extensively commented.
.SS "Lisp program"
.PP
These files contains Common lisp (see \fIhttps://common-lisp.net/\fP)
source code. And are used both as a way to configure the program
These files contains Common lisp (see \fIhttps://common-lisp.net/\fP)
source code. And are used both as a way to configure the program
and to write module for tinmop itself.
.PP
These files are the only way to configure program's keybindings:
sequence of pressing button to fire command commands (do not worry
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!).
.PP
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
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
\fBsevere\fP security damage.
.PP
Again in the configuration directory there is a (commented) file
named \fCinit.lisp\fP 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 \fC$HOME/.local/share/tinmop/\fP or
\fC$HOME/.config/tinmop/\fP (because, you know, data is code and code
Again in the configuration directory there is a (commented) file
named \fCinit.lisp\fP 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 \fC$HOME/.local/share/tinmop/\fP or
\fC$HOME/.config/tinmop/\fP (because, you know, data is code and code
is data) to be successfully loaded.
.PP
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.
.SH "First time start"
.PP
After the configuration the program can be started but we are not
ready to join the network 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
After the configuration the program can be started but we are not
ready to join the network 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).
.SH "How to get more help"
@ -264,11 +269,11 @@ in the directory \fC$HOME/.local/share/tinmop/\fP.
.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 \fIContributing\fP).
.IP \(em 4
\fC/etc/tinmop/default\-theme.conf\fP: default visual style
.IP \(em 4
\fC/etc/tinmop/shared.conf\fP: some default configuration not related to themes
\fC/etc/tinmop/shared.conf\fP: some default configuration not related to themes
.IP \(em 4
\fC/etc/tinmop/init.lisp\fP: system wide configuration
.IP \(em 4
@ -302,5 +307,5 @@ There are more people i borrowed code and data from, they are mentioned
in the file LINCENSES.org
.PP
This program is was born also with the help of CCCP: "Collettivo Computer
This program is was born also with the help of CCCP: "Collettivo Computer
Club Palermo".

8
src/main.lisp
View File

@ -81,10 +81,14 @@ etc.) happened"
:new-timeline command-line:*start-timeline*)))
(program-events:push-event refresh-event)))
(defun load-configuration-files ()
(swconf:load-config-file swconf:+shared-conf-filename+)
(swconf:load-config-file swconf:+conf-filename+))
(defun init ()
"Initialize the program"
(res:init)
(swconf:load-config-file)
(load-configuration-files)
(init-db)
(db-utils:with-ready-database (:connect nil)
(modules:load-module +starting-init-file+)
@ -129,7 +133,7 @@ etc.) happened"
(defun load-script-file ()
"Load (exexute) a lisp file used in requests of a command line switch"
(setf program-events:*process-events-immediately* t)
(swconf:load-config-file)
(load-configuration-files)
(init-db)
(db-utils:with-ready-database (:connect nil)
(client:init)

2
src/package.lisp
View File

@ -900,6 +900,8 @@
(:nicknames :swconf)
(:shadowing-import-from :misc :random-elt :shuffle)
(:export
:+conf-filename+
:+shared-conf-filename+
:+key-background+
:+key-foreground+
:+key-width+

2
src/software-configuration.lisp
View File

@ -78,6 +78,8 @@
(define-constant +conf-filename+ "main.conf" :test #'string=)
(define-constant +shared-conf-filename+ "shared.conf" :test #'string=)
(define-constant +field-separator-value+ "." :test #'string=)
(define-constant +field-separator+ :field-separator :test #'eq)