summaryrefslogtreecommitdiff
path: root/docs/tml-config.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tml-config.md')
-rw-r--r--docs/tml-config.md134
1 files changed, 134 insertions, 0 deletions
diff --git a/docs/tml-config.md b/docs/tml-config.md
new file mode 100644
index 0000000..451d47f
--- /dev/null
+++ b/docs/tml-config.md
@@ -0,0 +1,134 @@
+## Introduction
+
+**config** specifies settings for Terminal Media Launcher, including preferences, groups, entries, and file locations. Each line of `config` is read by tml unless the line is empty or the line begins with a '#'. tml will not run if no config file exists, so you will need to know how to write one
+
+## Table of Contents
+
+- [Creating a Group](#CreatingAGroup)
+ - [addGroup](#addGroup)
+ - [setLauncher](#setLauncher)
+ - [setFlags](#setFlags)
+- [Adding Entries](#AddingEntries)
+ - [add](#add)
+ - [addF](#addF)
+ - [addName](#addName)
+ - [addNameF](#addNameF)
+ - [addR](#addR)
+- [Settings](#Settings)
+ - [autoAlias](#autoAlias)
+ - [compMode](#compMode)
+ - [sort](#sort)
+- [Example](#Example)
+
+## Creating a Group <a name="CreatingAGroup"></a>
+
+tml will not work without any groups, so you will need to know how to create a group.
+
+### addGroup
+
+- **addGroup** *name*
+
+`addGroup` will create a new group with a specified name. By default this group is empty, with zero entries, no launching application specified, and no flags specified. If their is a space in the name, it must be written in quotes (ex. "TV Shows")
+
+### setLauncher
+
+- **setLauncher** *group* */path/to/launcher*
+
+`setLauncher` will set a group's launching application. If no launching application is specified for a group, tml will treat each entry in that group as an executable file. If their is a space in the path to the launching application, it must be written in quotes (ex. "/usr/bin/my launcher"). *Keep in mind that the path to the launching application should be absolute*.
+
+### setFlags
+
+- **setFlags** *group* *flags*
+
+`setFlags` will set the flags to be specified for the launching application. If no launching application is specified, any specified flags are ignored. If the specified flags contain a space, they must be written in quotes.
+
+## Adding Entries <a name=AddingEntries></a>
+
+tml will hide empty groups, so you will need to know how to add entries to a group.
+
+### add
+
+- **add** *path/to/file(s)* *group*
+
+`add` will add a file to a specified group if the path exists. It can also be used to add mutiple files to a group in one line using the '\*' operator (ex. `add /home/john/Pictures/* Pictures`). If the path to the file(s) contains space(s), it must be written in quotes.
+
+### addF
+
+- **addF** *arg* *group*
+
+`addF` will force an entry to be added to a specified group, regardless as to whether it is a valid file or not. Unlike `add`, `addF`'s argument does not need to be a valid file, but `addF` can only specify a single entry and does not support the '\*' operator. If the arg has a space in it, it must be written in quotes.
+
+### addName
+
+- **addName** *name* *path/to/file* *group*
+
+`addName`, like `add`, will add an entry to a specified group if the path exists. `addName` allows for a name to be specified for this entry (by default, the name is the same as the file name). Unlike `add`, only one entry can be added per line, as `addName` does not support the '\*' operator. If either the name or file path contain a space, they must be written in quotes.
+
+### addNameF
+
+- **addNameF** *name* *arg* *group*
+
+`addNameF` can be used in place of `addF` if you want the forced argument to have a different name displayed for the entry than is called in the system call to launch the entry. Otherwise, it is effectively the same as `addF`
+
+### addR
+
+- **addR** *path/to/files* *group*
+
+`addR` will recursively add entries to a group. `addR` functions like `add`, but will also search sub-directories for matches.
+
+## Settings
+
+If any of the following settings are specified, they should be at the top of the config file.
+
+### autoAlias
+
+- **autoAlias** *on/off*
+
+`autoAlias` will attempt to automatically give entries more human-readable names based on their filename by:
+
+1. Removing any characters inside parenthesis (including parenthesis)
+2. Replacing '-' and '\_' with a space character
+3. Replacing cases of multiple spaces in a row with only one space
+
+`autoAlias` is turned off by default.
+
+### compMode
+
+- **compMode WSL**
+
+At the moment, `compMode` can be turned on for using tml in Windows Subsystem for Linux. By default, `compMode` is turned off. *compMode may be removed in the future due to redundancy, as tml works natively in Windows*.
+
+### sort
+
+- **sort** *on/off*
+
+`sort` will sort entries of each group in alphabetical order (though not the list of groups). Turning off `sort` is only recommended when adding one item per line to a group. `sort` is turned on by default.
+
+## Example
+
+```
+autoAlias on
+
+# Adding a Group of Various Applications
+
+addGroup Applcations
+addName GIMP /usr/bin/gimp Applications
+addName Chromium /usr/bin/chromium-browser Applications
+addName Thunderbird /usr/bin/thunderbird Applications
+
+# Adding a Videos Group that contains mp4 files
+
+addGroup Videos
+setLauncher Videos /usr/bin/vlc
+add /home/john/Videos/*mp4 Videos
+
+# Adding a Pictures Group that contains only jpg and png files as well as all files from an external drive and a single desktop wallpaper
+
+addGroup Pictures
+setLauncher Pictures /usr/bin/sxiv
+setFlags "-s f"
+add /home/john/Pictures/*jpg Pictures
+add /home/john/Pictures/*png Pictures
+addR "/mnt/External_Drive/Johns Photos/*" Pictures
+addName "My Desktop Background" "/mnt/External_Drive/desktop wallpaper.jpg" Pictures
+```