From a3d8a9508f3d0edfffc1ab5791bb29b0ae7a79c5 Mon Sep 17 00:00:00 2001 From: louie Date: Fri, 10 Dec 2021 15:26:13 -0800 Subject: Changed name. May tidy up/differentiate 'Terminal Media Launcher' vs 'terminal-media-launcher' --- docs/README.md | 34 +++---- docs/terminal-media-launcher-config.5.gz | Bin 0 -> 2383 bytes docs/terminal-media-launcher-config.md | 156 +++++++++++++++++++++++++++++++ docs/terminal-media-launcher.1.gz | Bin 0 -> 1022 bytes docs/tml-config.5.gz | Bin 2330 -> 0 bytes docs/tml-config.md | 156 ------------------------------- docs/tml.1.gz | Bin 971 -> 0 bytes docs/windows_compile_instructions.md | 6 +- 8 files changed, 176 insertions(+), 176 deletions(-) create mode 100644 docs/terminal-media-launcher-config.5.gz create mode 100644 docs/terminal-media-launcher-config.md create mode 100644 docs/terminal-media-launcher.1.gz delete mode 100644 docs/tml-config.5.gz delete mode 100644 docs/tml-config.md delete mode 100644 docs/tml.1.gz (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 97b414a..08a5784 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,28 +1,28 @@ ## Introduction -**Terminal Media Launcher** is a command line utility to help streamline launching applications and other media. The goal of tml is to provide a fast, minimal, command line frontend with a Unix-like approach to setup and configuration. The program looks for a configuration file listing different groups of media and creates an ncurses menu from which to select from. If a configuration file is found, the program will draw two columns: one for groups, and one for entries. At the bottom of the window, a preview of the command execution is displayed. +**Terminal Media Launcher** is a command line utility to help streamline launching applications and other media. The goal of this program is to provide a fast, minimal, command line frontend with a Unix-like approach to setup and configuration. The program looks for a configuration file listing different groups of media and creates an ncurses menu from which to select from. If a configuration file is found, the program will draw two columns: one for groups, and one for entries. At the bottom of the window, a preview of the command execution is displayed. ## Compiling and Running For Windows instructions, see [here](windows_compile_instructions.md) -tml can be compiled on any system with make, gcc, and the ncurses library (libncurses-dev) installed. It can be compiled and installed on any Linux distribution, and can also be compiled and run on Windows 10. To compile and run tml: +terminal-media-launcher can be compiled on any system with make, gcc, and the ncurses library (libncurses-dev) installed. It can be compiled and installed on any Linux distribution, and can also be compiled and run on Windows 10. To compile and run terminal-media-launcher: 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 +2. Run `make` in the directory the repository was cloned into. This will create a file called `terminal-media-launcher` +3. `./terminal-media-launcher` to run the program -Note that tml will not run until you have created a configuration file. +Note that terminal-media-launcher will not run until you have created a configuration file. ### Installation -tml can be installed on Linux by running: +terminal-media-launcher can be installed on Linux by running: ``` sudo make install ``` -This will install `tml` to `/usr/local/bin/tml` as well as man pages `tml` and `tml-config`. +This will install `terminal-media-launcher` to `/usr/local/bin/terminal-media-launcher` as well as man pages `terminal-media-launcher` and `terminal-media-launcher-config`. To uninstall these files: ``` @@ -31,13 +31,13 @@ sudo make uninstall ### Create Desktop Entry -If tml is installed (see above), a Desktop Entry can be created on Linux by running: +If terminal-media-launcher is installed (see above), a Desktop Entry can be created on Linux by running: ``` sudo make desktop-entry ``` -This will create a desktop entry at `/usr/local/share/applications/tml.desktop`. +This will create a desktop entry at `/usr/local/share/applications/terminal-media-launcher.desktop`. ## Screenshots @@ -46,23 +46,23 @@ This will create a desktop entry at `/usr/local/share/applications/tml.desktop`. ## Configuration File -By default, tml searches in the following order for a configuration file: +By default, terminal-media-launcher searches in the following order for a configuration file: ### Linux -1. `$HOME/.config/tml/config` -2. `$HOME/.tml/config` +1. `$HOME/.config/terminal-media-launcher/config` +2. `$HOME/.terminal-media-launcher/config` ### Windows -1. `%APPDATA%\tml\config` +1. `%APPDATA%\terminal-media-launcher\config` A different configuration file location can also be specified with the `-c` flag: ``` -tml -c /path/to/config +terminal-media-launcher -c /path/to/config ``` -For Documentation of the configuration file, see [tml-config](tml-config.md). -For a help message and list of flags, `tml --help`. -If you installed tml, you can also consult **tml**(1) and **tml-config**(5). +For Documentation of the configuration file, see [terminal-media-launcher-config](terminal-media-launcher-config.md). +For a help message and list of flags, `terminal-media-launcher --help`. +If you installed terminal-media-launcher, you can also consult **terminal-media-launcher**(1) and **terminal-media-launcher-config**(5). diff --git a/docs/terminal-media-launcher-config.5.gz b/docs/terminal-media-launcher-config.5.gz new file mode 100644 index 0000000..23250a5 Binary files /dev/null and b/docs/terminal-media-launcher-config.5.gz differ diff --git a/docs/terminal-media-launcher-config.md b/docs/terminal-media-launcher-config.md new file mode 100644 index 0000000..3d12f97 --- /dev/null +++ b/docs/terminal-media-launcher-config.md @@ -0,0 +1,156 @@ +## Introduction + +**config** specifies settings for Terminal Media Launcher, including preferences, groups, entries, and file locations. Each line of `config` is read by terminal-media-launcher unless the line is empty or the line begins with a '#'. terminal-media-launcher can automatically generate a configuration file if no such file is found. An automatically generated configuration file will create groups for Music, Pictures, and Videos, and add entries to each group from the respective directory in the user's home directory. It is highly recommended that the user edit the configuration file manually. + +## Table of Contents + +- [Creating a Group](#CreatingAGroup) + - [addGroup](#addgroup) + - [setLauncher](#setlauncher) + - [setLauncherRaw](#setlauncherraw) + - [setFlags](#setflags) +- [Adding Entries](#AddingEntries) + - [add](#add) + - [addF](#addf) + - [addName](#addname) + - [addNameF](#addnamef) + - [addR](#addr) + - [hide](#hide) + - [hideFile](#hidefile) +- [Settings](#settings) + - [autoAlias](#autoalias) + - [foldCase](#foldcase) + - [sort](#sort) +- [Example](#example) + +## Creating a Group + +terminal-media-launcher 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 there 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, terminal-media-launcher will treat each entry in that group as an executable file. If there 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*. + +### setLauncherRaw + +- **setLauncherRaw** *group* */path/to/launcher* + +`setLauncherRaw` is identical to `setLauncher` with the exception that the launcher application specified will not be wrapped in quotes for the system call when a member of the group is launched. This can be used to specify more complex launching instructions. + +### 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 + +terminal-media-launcher 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** *new-entry* *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* *new-entry* *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. + +### hide + +- **hide** *entry* *group* + +`hide` will remove a specified entry from a specified group. The entry argument should refer to the entry's name, rather than the entry's path. This option may be useful to hide certain entries after adding entries with the '\*' operator. *At the moment, hide can only hide a single entry*. + +### hideFile + +- **hideFile** *path* *group* + +`hideFile` has the exact same functionality as `hide`, but takes the absolute path of the entry to hide as the first argument, instead of the name. + +## 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 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 +4. Removing file extensions (if the file has an extension) + +`autoAlias` is turned off by default. + +### foldCase + +- **foldCase** *on/off* + +Entering any non-traversal input in terminal-media-launcher can be used to jump to a group or entry. For instance, hitting 'f' on the keyboard will jump the cursor to the next group or entry that starts with an 'f'. *foldCase* determines whether or not this functionality is **case insensitive (on)** or **case sensitive (off)**. *foldCase* is turned on by default. + +### 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 Applications +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 Pictures "-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 +``` diff --git a/docs/terminal-media-launcher.1.gz b/docs/terminal-media-launcher.1.gz new file mode 100644 index 0000000..de27be3 Binary files /dev/null and b/docs/terminal-media-launcher.1.gz differ diff --git a/docs/tml-config.5.gz b/docs/tml-config.5.gz deleted file mode 100644 index fde914d..0000000 Binary files a/docs/tml-config.5.gz and /dev/null differ diff --git a/docs/tml-config.md b/docs/tml-config.md deleted file mode 100644 index 41398c1..0000000 --- a/docs/tml-config.md +++ /dev/null @@ -1,156 +0,0 @@ -## 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 can automatically generate a configuration file if no such file is found. An automatically generated configuration file will create groups for Music, Pictures, and Videos, and add entries to each group from the respective directory in the user's home directory. It is highly recommended that the user edit the configuration file manually. - -## Table of Contents - -- [Creating a Group](#CreatingAGroup) - - [addGroup](#addgroup) - - [setLauncher](#setlauncher) - - [setLauncherRaw](#setlauncherraw) - - [setFlags](#setflags) -- [Adding Entries](#AddingEntries) - - [add](#add) - - [addF](#addf) - - [addName](#addname) - - [addNameF](#addnamef) - - [addR](#addr) - - [hide](#hide) - - [hideFile](#hidefile) -- [Settings](#settings) - - [autoAlias](#autoalias) - - [foldCase](#foldcase) - - [sort](#sort) -- [Example](#example) - -## Creating a Group - -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 there 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 there 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*. - -### setLauncherRaw - -- **setLauncherRaw** *group* */path/to/launcher* - -`setLauncherRaw` is identical to `setLauncher` with the exception that the launcher application specified will not be wrapped in quotes for the system call when a member of the group is launched. This can be used to specify more complex launching instructions. - -### 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 - -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** *new-entry* *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* *new-entry* *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. - -### hide - -- **hide** *entry* *group* - -`hide` will remove a specified entry from a specified group. The entry argument should refer to the entry's name, rather than the entry's path. This option may be useful to hide certain entries after adding entries with the '\*' operator. *At the moment, hide can only hide a single entry*. - -### hideFile - -- **hideFile** *path* *group* - -`hideFile` has the exact same functionality as `hide`, but takes the absolute path of the entry to hide as the first argument, instead of the name. - -## 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 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 -4. Removing file extensions (if the file has an extension) - -`autoAlias` is turned off by default. - -### foldCase - -- **foldCase** *on/off* - -Entering any non-traversal input in tml can be used to jump to a group or entry. For instance, hitting 'f' on the keyboard will jump the cursor to the next group or entry that starts with an 'f'. *foldCase* determines whether or not this functionality is **case insensitive (on)** or **case sensitive (off)**. *foldCase* is turned on by default. - -### 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 Applications -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 Pictures "-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 -``` diff --git a/docs/tml.1.gz b/docs/tml.1.gz deleted file mode 100644 index 33c4e83..0000000 Binary files a/docs/tml.1.gz and /dev/null differ diff --git a/docs/windows_compile_instructions.md b/docs/windows_compile_instructions.md index 8966263..21530fb 100644 --- a/docs/windows_compile_instructions.md +++ b/docs/windows_compile_instructions.md @@ -10,13 +10,13 @@ Compiling on Windows requires access to the MinGW toolchain. The easiest way to 4. `pacman -S git mingw-w64-x86_64-gcc mingw-w64-x86_64-ncurses make` to install necessary packages -5. `git clone https://github.com/lshprung/tml` to clone the repository +5. `git clone https://github.com/lshprung/terminal-media-launcher` to clone the repository -6. `cd tml` to enter the repository +6. `cd terminal-media-launcher` to enter the repository 7. `make` to compile -If you did everything correctly, compilation should succeed. Open File Explorer in the current directory (can be done by running `explorer .` in MSYS2 terminal) and double click the generated executable (should be called tml.exe) +If you did everything correctly, compilation should succeed. Open File Explorer in the current directory (can be done by running `explorer .` in MSYS2 terminal) and double click the generated executable (should be called terminal-media-launcher.exe) ## Resolving Missing .dll Files -- cgit