diff options
| -rw-r--r-- | docs/README.md | 23 | ||||
| -rw-r--r-- | docs/tml-config.md | 134 |
2 files changed, 157 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..14ce9d6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,23 @@ +## Introduction + +**Terminal Media Launcher** is a command line utility to help streamline launching applications and other media. The program looks for a config file listing different groups of media and creates an ncurses menu from which to select from. + +## Compiling and Running + +tml can be installed on any system with gcc and the ncurses library installed. It has been tested to work on Ubuntu and Windows 10. To compile and run tml: + +1. Clone the repository +2. Run `make` in the directory the repository was cloned into. This will create a file called `tml` +3. `./tml` to run the program + +Note that tml will not run until you have created a config file. + +## Config File + +By default, tml searches in the following order for a config file: + +1. `$HOME/.config/tml/config` +2. `$HOME/.tml/config` +3. `config` (in the current directory) + +A different config file location can also be specified with the `-c` flag. For Documentation of the config file, see [tml-config](tml-config.md) 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 +``` |