Update documentation

- Update README
- Update CHNAGELOG
- Update `--config-file` argument help message

Author: CyanVoxel

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.2.0-alpha] - 2024-05-14
+
+### Added
+
+- Full macOS and Linux support
+- Ability to apply tags to multiple selections at once
+- Right-click context menu for opening files or their locations
+- Support for all filetypes inside of the library
+- Configurable filetype blacklist
+- Option to automatically open last used library on startup
+- Tool to convert folder structure to tag tree
+- SIGTERM handling in console window
+- Keyboard shortcuts for basic functions
+- Basic support for plaintext thumbnails
+- Default icon for files with no thumbnail support
+- Menu action to close library
+- All tags now show in the "Add Tag" panel by default
+- Modal view to view and manage all library tags
+- Build scripts for Windows and macOS
+- Help menu option to visit the GitHub repository
+- Toggleable "Recent Libraries" list in the entry side panel
+
+### Fixed
+
+- Fixed errors when performing actions with no library open
+- Fixed bug where built-in tags were duplicated upon saving
+- QThreads are now properly terminated on application exit
+- Images with rotational EXIF data are now properly displayed
+- Fixed "truncated" images causing errors
+- Fixed images with large resolutions causing errors
+
+### Changed
+
+- Updated minimum Python version to 3.12
+- Various UI improvements
+  - Improved legibility of the Light Theme (still a WIP)
+  - Updated Dark Theme
+  - Added hand cursor to several clickable elements
+- Fixed network paths not being able to load
+- Various code cleanup and refactoring
+- New application icons
+
+### Known Issues
+- Using and editing multiple entry fields of the same type may result in incorrect field(s) being updated
+- Adding Favorite or Archived tags via the thumbnail badges may apply the tag(s) to incorrect fields
+- Searching for tag names with spaces does not currently function as intended
+	- A temporary workaround it to omit spaces in tag names when  searching
+- Sorting fields using the "Sort Fields" macro may result in edit icons being shown for incorrect fields
+
 ## [9.1.0-alpha] - 2024-04-22
 
 ### Added

README.md

@@ -1,4 +1,4 @@
-# TagStudio (Preview/Alpha): A User-Focused Document Management System
+# TagStudio (Alpha): A User-Focused Document Management System
 
 <p align="center">
   <img width="60%" src="github_header.png">
@@ -15,6 +15,7 @@ TagStudio is a photo & file organization application with an underlying system t
 </p>
 
 ## Contents
+
 - [Goals](#goals)
 - [Priorities](#priorities)
 - [Current Features](#current-features)
@@ -45,67 +46,27 @@ TagStudio is a photo & file organization application with an underlying system t
   - Description, Notes (Multiline Text Fields)
   - Tags, Meta Tags, Content Tags (Tag Boxes)
 - Create rich tags composed of a name, a list of aliases, and a list of “subtags” - being tags in which these tags inherit values from.
-- Search for entries based on tags, metadata, or filename (using `filename: <query>`)
+- Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`)
 - Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`.
 
 > [!NOTE]
 > For more information on the project itself, please see the [FAQ](#faq) section and other docs.
 
 ## Installation
-> [!CAUTION]
-> TagStudio is only currently verified to work on Windows. I've run into issues with the Qt code running on Linux, but I don't know how severe these issues are. There's also likely bugs regarding filenames and portability of the databases across different OSes.
-
-### Prerequisites
-
-- Python 3.12
-
-### Creating the Virtual Environment
-
-*Skip this step if launching from the .sh script on Linux.*
-
-1. In the root repository directory, create a python virtual environment:  
-   `python3 -m venv .venv`
-2. Activate your environment:
-
-- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
-- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
-- Linux/macOS: `source .venv/bin/activate`
-
-3. Install the required packages:  
-   `pip install -r requirements.txt`
 
-_Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._
+To download TagStudio, visit the [Releases](https://github.com/TagStudioDev/TagStudio/releases) section of the GitHub repository and download the latest release for your system. TagStudio is available for **Windows**, **macOS** _(Apple Silicon & Intel)_, and **Linux**. Windows and Linux builds are also available in portable versions if you want a more self-contained executable to move around.
 
-### Launching
-
-> [!NOTE]
-> Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3`. 
+Once downloaded, launch the corresponding TagStudio executable to start the program. Once open, go to **"File -> Create/Open Library"** to create your first library from a directory!
 
 #### Optional Arguments
 
+Optional arguments to pass to the program.
+
 > `--open <path>` / `-o <path>`
 > Path to a TagStudio Library folder to open on start.
 
-#### Windows
-
-To launch TagStudio, launch the `start_win.bat` file. You can modify this .bat file or create a shortcut and add one or more additional arguments if desired.
-
-Alternatively, with the virtual environment loaded, run the python file at `tagstudio\tag_studio.py` from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`.
-
-> [!CAUTION]
-> TagStudio on Linux & macOS likely won't function correctly at this time. If you're trying to run this in order to help test, debug, and improve compatibility, then charge on ahead!
-
-#### macOS
-
-With the virtual environment loaded, run the python file at "tagstudio/tag_studio.py" from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`. When launching the program in the future, remember to activate the virtual environment each time before launching *(an easier method is currently being worked on).*
-
-#### Linux
-
-Run the "TagStudio.sh" script, and the program should launch! (Make sure that the script is marked as executable). Note that launching from the script from outside of a terminal will not launch a terminal window with any debug or crash information. If you wish to see this information, just launch the shell script directly from your terminal with `sh TagStudio.sh`.
-
-##### NixOS
-
-Use the provided `flake.nix` file to create and enter a working environment by running `nix develop`. Then, run the above `TagStudio.sh` script.
+> `--config-file <path>` / `-c <path>`
+> Path to a TagStudio Library folder to open on start.
 
 ## Usage
 
@@ -197,11 +158,56 @@ Import JSON sidecar data generated by [gallery-dl](https://github.com/mikf/galle
 > [!CAUTION]
 > This feature is not supported or documented in any official capacity whatsoever. It will likely be rolled-in to a larger and more generalized sidecar importing feature in the future.
 
+## Creating a Development Environment
+
+If you're interested in contributing to TagStudio or just wish to poke around the live codebase, here are instructions for setting up the Python project.
+
+### Prerequisites
+
+- Python 3.12
+
+### Creating a Python Virtual Environment
+
+> [!NOTE]
+> Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3`. You can check to see which alias you system uses and if it's for the correct Python version by typing `python3 --version` (or whichever alias) into your terminal.
+
+_Skip these steps if launching from the .sh script on Linux/macOS._
+
+1. In the root repository directory, create a python virtual environment:  
+   `python3 -m venv .venv`
+2. Activate your environment:
+
+- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
+- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
+- Linux/macOS: `source .venv/bin/activate`
+
+3. Install the required packages:  
+   `pip install -r requirements.txt`
+
+_Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._
+
+### Launching Development Environment
+
+- **Windows** (start_win.bat)
+
+  - To launch TagStudio, launch the `start_win.bat` file. You can modify this .bat file or create a shortcut and add one or more additional arguments if desired.
+
+- **Linux/macOS** (TagStudio.sh)
+
+  - Run the "TagStudio.sh" script, and the program should launch! (Make sure that the script is marked as executable if on Linux). Note that launching from the script from outside of a terminal will not launch a terminal window with any debug or crash information. If you wish to see this information, just launch the shell script directly from your terminal with `./TagStudio.sh`.
+
+  - **NixOS** (TagStudio.sh)
+    - Use the provided `flake.nix` file to create and enter a working environment by running `nix develop`. Then, run the `TagStudio.sh` script.
+
+- **Any** (No Scripts)
+
+  - Alternatively, with the virtual environment loaded, run the python file at `tagstudio\tag_studio.py` from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`.
+
 ## FAQ
 
 ### What State Is the Project Currently In?
 
-As of writing (Alpha v9.1.0) the project is in a “useable” state, however it lacks proper testing and quality of life features. Currently the program has only been verified to work properly on Windows, and is unlikely to properly run on Linux or macOS in its current state, however this functionality is a priority going forward with testers.
+As of writing (Alpha v9.2.0) the project is in a useable state, however it lacks proper testing and quality of life features.
 
 ### What Features Are You Planning on Adding?
 
@@ -214,18 +220,16 @@ Of the several features I have planned for the project, these are broken up into
   - Boolean Search
   - Coexisting Text + Tag Search
   - Searchable File Metadata
-- Tag management view
-- Applying metadata via multi-selection
+- Comprehensive Tag management tab
 - Easier ways to apply tags in bulk
   - Tag Search Panel
   - Recent Tags Panel
   - Top Tags Panel
   - Pinned Tags Panel
-- Apply tags based on system folders
 - Better (stable, performant) library grid view
 - Improved entry relinking
 - Cached thumbnails
-- Collations
+- Tag-like Groups
 - Resizable thumbnail grid
 - User-defined metadata fields
 - Multiple directory support
@@ -235,49 +239,54 @@ Of the several features I have planned for the project, these are broken up into
 - Better internal API for accessing Entries, Tags, Fields, etc. from the library.
 - Proper testing workflow
 - Continued code cleanup and modularization
-- Reassessment of save file structure in order to prioritize portability (leading to exportable tags, presets, etc)
+- Exportable/importable library data including "Tag Packs"
 
 #### Future Features
 
 - Support for multiple simultaneous users/clients
 - Draggable files outside the program
-- Ability to ignore specific files
+- Comprehensive filetype whitelist
 - A finished “macro system” for automatic tagging based on predetermined criteria.
 - Different library views
 - Date and time fields
 - Entry linking/referencing
 - Audio waveform previews
 - 3D object previews
 - Additional previews for miscellaneous file types
-- Exportable/sharable tags and settings
 - Optional global tags and settings, spanning across libraries
 - Importing & exporting libraries to/from other programs
 - Port to a more performant language and modern frontend (Rust?, Tauri?, etc.)
 - Plugin system
 - Local OCR search
 - Support for local machine learning-based tag suggestions for images
-- Mobile version
+- Mobile version _(FAR future)_
 
 #### Features I Likely Won’t Add/Pull
-- Native Cloud Integration 
+
+- Native Cloud Integration
   - There are plenty of services already (native or third-party) that allow you to mount your cloud drives as virtual drives on your system. Pointing TagStudio to one of these mounts should function similarly to what native integration would look like.
 - Native ChatGPT/Non-Local LLM Integration
-  - This could mean different things depending on what you're intending. Whether it's trying to use an LLM to replace the native search, or to trying to use a model for image recognition, I'm not interested in hooking people's TagStudio libraries into non-local LLMs such as ChatGPT and/or turn the program into a "chatbot" interface (see: [Goals/Privacy](#goals)). I wouldn't, however, mind using **locally** hosted models to provide the *optional* ability for additional searching and tagging methods (especially when it comes to facial recognition).
+  - This could mean different things depending on what you're intending. Whether it's trying to use an LLM to replace the native search, or to trying to use a model for image recognition, I'm not interested in hooking people's TagStudio libraries into non-local LLMs such as ChatGPT and/or turn the program into a "chatbot" interface (see: [Goals/Privacy](#goals)). I wouldn't, however, mind using **locally** hosted models to provide the _optional_ ability for additional searching and tagging methods (especially when it comes to facial recognition).
 
 ### Why Is the Version Already v9?
 
 I’ve been developing this project over several years in private, and have gone through several major iterations and rewrites in that time. This “major version” is just a number at the end of the day, and if I wanted to I couldn’t released this as “Version 0” or “Version 1.0”, but I’ve decided to stick to my original version numbers to avoid needing to go in and change existing documentation and code comments. Version 10 is intended to include all of the “Priority Features” I’ve outlined in the [previous](#what-features-are-you-planning-on-adding) section. I’ve also labeled this version as an Alpha, and will likely reset the numbers when a feature-complete beta is reached.
 
 ### Wait, Is There a CLI Version?
 
-As of right now, no. However, I _did_ have a CLI version in the recent past before dedicating my efforts to the Qt GUI version. I’ve left in the currently-inoperable CLI code just in case anyone was curious about it. Also yes, it’s just a bunch of glorified print statements (_the outlook for some form of curses on Windows didn’t look great at the time, and I just needed a driver for the newly refactored code...)._
+As of right now, **no**. However, I _did_ have a CLI version in the recent past before dedicating my efforts to the Qt GUI version. I’ve left in the currently-inoperable CLI code just in case anyone was curious about it. Also yes, it’s just a bunch of glorified print statements (_the outlook for some form of curses on Windows didn’t look great at the time, and I just needed a driver for the newly refactored code...)._
 
 ### Can I Contribute?
 
 **Yes!!** I recommend taking a look at the [Priority Features](#priority-features), [Future Features](#future-features), and [Features I Won't Pull](#features-i-likely-wont-addpull) lists, as well as the project issues to see what’s currently being worked on. Please do not submit pull requests with new feature additions without opening up an issue with a feature request first.
 
-Code formatting is automatically checked via [ruff](https://docs.astral.sh/ruff/). 
+Code formatting is automatically checked via [Ruff](https://docs.astral.sh/ruff/).
 
-To format the code manually, install ruff via `pip install -r requirements-dev.txt` and then run `ruff format` 
+To format the code manually, install ruff via `pip install -r requirements-dev.txt` and then run `ruff format`
 
 To format the code automatically before each commit, there's a configured action available for `pre-commit` hook. Install it by running `pre-commit install`. The hook will be executed each time on running `git commit`.
+
+More structured documentation on contribution requirements is on its way, but for now:
+
+- Use `pathlib` in favor of `os.path`
+- Try to make new UI additions match the existing style of the application

tagstudio/tag_studio.py

@@ -34,7 +34,7 @@ def main():
         "--config-file",
         dest="config_file",
         type=str,
-        help="Path to a TagStudio.ini config file to use",
+        help="Path to a TagStudio .ini or .plist config file to use.",
     )
 
     # parser.add_argument('--browse', dest='browse', action='store_true',