diff --git a/doc/man.org b/doc/man.org index 28ef3ff..638e8df 100644 --- a/doc/man.org +++ b/doc/man.org @@ -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". diff --git a/doc/tinmop.man b/doc/tinmop.man index bed8daa..0b62541 100644 --- a/doc/tinmop.man +++ b/doc/tinmop.man @@ -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". diff --git a/src/main.lisp b/src/main.lisp index 6cc25da..f6a27bd 100644 --- a/src/main.lisp +++ b/src/main.lisp @@ -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) diff --git a/src/package.lisp b/src/package.lisp index a752d08..9931114 100644 --- a/src/package.lisp +++ b/src/package.lisp @@ -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+ diff --git a/src/software-configuration.lisp b/src/software-configuration.lisp index 470412c..bac2519 100644 --- a/src/software-configuration.lisp +++ b/src/software-configuration.lisp @@ -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)