diff --git a/doc/Entry.md b/doc/Entry.md new file mode 100644 index 00000000..f80aceaf --- /dev/null +++ b/doc/Entry.md @@ -0,0 +1,25 @@ +# Entry + +Entries are the units that fill a [library](/doc/Library.md). Each one corresponds to a file, holding a reference to it along with the metadata associated with it. + +### Entry Object Structure + +1. `id`: + - Int, Unique, **Required** + - The ID for the Entry. + - Used for internal processing +2. `filename`: + - String, **Required** + - The filename with extension of the referenced media file. +3. `path`: + - String, **Required**, OS Agnostic + - The folder path in which the media file is located in. +4. [`fields`](/doc/Field.md): + - List of dicts, Optional + - A list of Field ID/Value dicts. + +NOTE: _Entries currently have several unused optional fields intended for later features._ + +## Retrieving Entries based on [Tag](/doc/Tag.md) Cluster + +By default when querying Entries, each Entry's `tags` list (stored in the form of Tag `id`s) is compared against the Tag `id`s in a given Tag cluster (list of Tag `id`s) or appended clusters in the case of multi-term queries. The type of comparison depends on the type of query and whether or not it is an inclusive or exclusive query, or a combination of both. This default searching behavior is done in _O(n)_ time, but can be sped up in the future by building indexes on certain search terms. These indexes can be stored on disk and loaded back into memory in future sessions. These indexes will also need to be updated as new Tags and Entries are added or edited. \ No newline at end of file diff --git a/doc/Field.md b/doc/Field.md new file mode 100644 index 00000000..1f91974e --- /dev/null +++ b/doc/Field.md @@ -0,0 +1,23 @@ +# Field + +Fields are the building blocks of metadata stored in [entries](/doc/Entry.md). Fields have several base types for representing different kinds of information, including: + +#### `text_line` + - A string of text, displayed as a single line. + - e.g: Title, Author, Artist, URL, etc. +#### `text_box` + - A long string of text displayed as a box of text. + - e.g: Description, Notes, etc. +#### `tag_box` + - A box of [tags](/doc/Tag.md) defined and added by the user. + - Multiple tag boxes can be used to separate classifications of tags. + - e.g: Content Tags, Meta Tags, etc. +#### `datetime` [WIP] + - A date and time value. + - e.g: Date Created, Date Modified, Date Taken, etc. +#### `checkbox` [WIP] + - A simple two-state checkbox. + - Can be associated with a tag for quick organization. + - e.g: Archive, Favorite, etc. +#### `collation` [obsolete] + - Previously used for associating files to be used in a [collation](/doc/Macro.md/#create-collage), will be removed in favor of a more flexible feature in future updates. diff --git a/doc/Home.md b/doc/Home.md new file mode 100644 index 00000000..fc28baa2 --- /dev/null +++ b/doc/Home.md @@ -0,0 +1,19 @@ +# Welcome to the TagStudio Wiki! + +> [!WARNING] +> This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates. + +![Under Construction](https://i0.wp.com/www.bapl.org/wp-content/uploads/2019/02/old-under-construction-gif.gif) + +## Table of Contents + +- [Library](/doc/Library.md) +- [Entries](/doc/Entry.md) +- [Fields](/doc/Field.md) +- [Tags](/doc/Tag.md) +- [Tools & Macros](/doc/Macro.md) + +--- + +### Database-Update +The "Database Update", "DB Migration", or "SQLite Migration" is an upcoming update to TagStudio which will replace the current JSON [library](/doc/Library.md) with a SQL-based one, and will additionally include some fundamental changes to how some features such as [tags](/doc/Tag.md) will work. diff --git a/doc/Library.md b/doc/Library.md new file mode 100644 index 00000000..47f2af33 --- /dev/null +++ b/doc/Library.md @@ -0,0 +1,10 @@ +# Library + +The library is how TagStudio represents your chosen directory, with every file inside of it being displayed as an [entry](/doc/Entry.md). You can have as many or few libraries as you wish, since each libraries' data is stored within a "`.TagStudio`" folder at its root. +Note that this means [tags](/doc/Tag.md) you create only exist *per-library*. + +### Library contents +- [Entries](/doc/Entry.md) +- [Fields](/doc/Field.md) +- [Tags](/doc/Tag.md) +- [Macros](/doc/Macro.md) diff --git a/doc/Macro.md b/doc/Macro.md new file mode 100644 index 00000000..e5fe16c4 --- /dev/null +++ b/doc/Macro.md @@ -0,0 +1,41 @@ +# Tools & Macros + +Tools and macros are features that serve to create a more fluid [library](/doc/Library.md)-managing process, or provide some extra functionality. Please note that some are still in active development and will be fleshed out in future updates. + +## Tools + +### Fix Unlinked Entries + +This tool displays the number of unlinked [entries](/doc/Entry.md), and some options for their resolution. +1. Refresh + - Scans through the library and updates the unlinked entry count. +2. Search & Relink + - Attempts to automatically find and reassign missing files. +3. Delete Unlinked Entries + - Displays a confirmation prompt containing the list of all missing files to be deleted before committing to or cancelling the operation. + +### Fix Duplicate Files + +This tool allows for management of duplicate files in the library using a [DupeGuru](https://dupeguru.voltaicideas.net/) file. +1. Load DupeGuru File + - load the "results" file created from a DupeGuru scan +2. Mirror Entries + - Duplicate entries will have their contents mirrored across all instances. This allows for duplicate files to then be deleted with DupeGuru as desired, without losing the [field](/doc/Field.md) data that has been assigned to either. (Once deleted, the "Fix Unlinked Entries" tool can be used to clean up the duplicates) + +### Create Collage + +This tool is a preview of an upcoming feature. When selected, TagStudio will generate a collage of all the contents in a Library, which can be found in the Library folder ("/your-folder/.TagStudio/collages/"). Note that this feature is still in early development, and doesn't yet offer any customization options. + +## Macros + +### Auto-fill [WIP] + +Tool is in development and will be documented in future update. + +### Sort fields + +Tool is in development, will allow for user-defined sorting of [fields](/doc/Field.md). + +### Folders to Tags + +Creates tags from the existing folder structure in the library, which are previewed in a hierarchy view for the user to confirm. A tag will be created for each folder and applied to all entries, with each subfolder being linked to the parent folder as a [parent tag](/doc/Tag.md#subtags). Tags will initially be named after the folders, but can be fully edited and customized afterwards. \ No newline at end of file diff --git a/doc/Tag.md b/doc/Tag.md new file mode 100644 index 00000000..644ca25f --- /dev/null +++ b/doc/Tag.md @@ -0,0 +1,68 @@ +# Tag + +Tags are user-defined attributes made up of one or more keywords, aliases, and relationships to other tags. A person, place, thing, concept, you name it! Tags allow for a more sophisticated way to organize and search [entries](/doc/Entry.md) thanks to their aliases, parent tags, and more. +Tags can be as simple or complex as wanted, so that any user can tune TagStudio to fit their needs. + +Among the things that make tags so useful, aliases give the ability to contain alternate names and spellings, making searches intuitive and expansive. Furthermore, parent-tags/subtags offer relational organization capabilities for the structuring and connection of the [library's](/doc/Library.md) contents. + +## Tag Object Structure + +#### `id` +ID for the tag. +- Int, Unique, Required +- Used for internal processing +#### `name` +The normal name of the tag, with no shortening or specification. +- String, Required +- Doesn't have to be unique +- Used for display, searching, and storing +#### `shorthand` +The shorthand name for the tag. Works like an alias but is used for specific display purposes. +- String, Optional +- Doesn't have to be unique +- Used for display and searching +#### `aliases` +Alternate names for the tag. +- List of Strings, Optional +- Recommended to be unique to this tag +- Used for searching +#### `subtags` +Other Tags that make up properties of this tag. Also called "parent tags". +- List of Strings, Optional +- Used for display (first parent tag only) and searching. +#### `color` +A color name string for customizing the tag's display color +- String, Optional +- Used for display + +## Tag Search Examples: + +Using for example, a library of files including some tagged with the following tags: + +| Tag | `name` | `shorthand` | `aliases` | `parent tags` | +| ------------------- | ------------------- | ----------- | ---------------------- | -------------------------------------------- | +| *League of Legends* | "League of Legends" | "LoL" | ["League"] | ["Game", "Fantasy"] | +| *Arcane* | "Arcane" | "" | [] | ["League of Legends", "Cartoon"] | +| *Jinx (LoL)* | "Jinx Piltover" | "Jinx" | ["Jinxy", "Jinxy Poo"] | ["League of Legends", "Arcane", "Character"] | +| *Zander (Arcane)* | "Zander Zanderson" | "Zander" | [] | ["Arcane", "Character"] | +| *Mr. Legend (LoL)* | "Mr. Legend" | "" | [] | ["League of Legends", "Character"] | + +**The query "Arcane" will display results tagged with:** + +| Tag | Cause of Inclusion | Tag Tree Lineage | +| --------------- | -------------------------------- | -------------------------- | +| Arcane | Direct match of tag name | "Arcane" | +| Jinx (LoL) | Search term is set as parent tag | "Jinx (LoL) > Arcane" | +| Zander (Arcane) | Search term is set as parent tag | "Zander (Arcane) > Arcane" | + +**The query "League of Legends" will display results tagged with:** + +| Tag | Cause of Inclusion | Tag Tree Lineage | +| ----------------- | ------------------------------------------------------ | ---------------------------------------------- | +| League of Legends | Direct match of tag name | "League of Legends" | +| Arcane | Search term is set as parent tag | "Arcane > League of Legends" | +| Jinx (LoL) | Search term is set as parent tag | "Jinx (LoL) > League of Legends" | +| Mr. Legend (LoL) | Search term is set as parent tag | "Mr. Legend (LoL) > League of Legends" | +| Zander (Arcane) | Search term is a parent tag of a tag set as parent tag | "Zander (Arcane) > Arcane > League of Legends" | + +Note: The query "LoL" will display the same results as the above example since "LoL" is the shorthand for "League of Legends". diff --git a/doc/documentation.md b/doc/documentation.md deleted file mode 100644 index 5718e6b6..00000000 --- a/doc/documentation.md +++ /dev/null @@ -1,189 +0,0 @@ -# TagStudio Documentation (Alpha v9.1.0) - -## _A User-Focused Document Management System_ - -> [!WARNING] -> This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates. - -## Contents -- [Library](#library) -- [Fields](#fields) -- [Entries](#entries) -- [Tags](#tags) -- [Retrieving Entries](#retrieving-entries-based-on-tag-cluster) -- [Missing File Resolution](#missing-file-resolution) - -## Library - -The Library is how TagStudio represents your chosen directory. In this Library or Vault system, all files within this directory are represented by Entries, which then contain metadata Fields. All TagStudio data for a Library is stored within a `.TagStudio` folder at the root of the Library's directory. Internal Library objects include: - -- Fields (v9+) - - Text Line (Title, Author, Artist, URL) - - Text Box (Description, Notes) - - Tag Box (Tags, Content Tags, Meta Tags) - - Datetime (Date Created, Date Modified, Date Taken) [WIP] - - Collation (Collation) [WIP] - - `name: str`: Collation Name - - `page: int`: Page # - - Checkbox (Archive, Favorite) [WIP] - - Drop Down (Group of Tags to select one from) [WIP] -- Entries (v1+) -- Tags (v7+) -- Macros (v9/10+) - -## Fields - -Fields are the building blocks of metadata stored in Entires. Fields have several base types for representing different types of information, including: - -- `text_line` - - A string of text, displayed as a single line. - - Useful for Titles, Authors, URLs, etc. -- `text_box` - - A long string of text displayed as a box of text. - - Useful for descriptions, notes, etc. -- `datetime` [WIP] - - A date and time value. -- `tag_box` - - A box of tags added by the user. - - Multiple tag boxes can be used to separate classifications of tags, ex. 'Content Tags' and 'Meta Tags'. -- `checkbox` [WIP] - - A two-state checkbox. - - Can be associated with a tag for quick organization. -- `collation` [WIP] - - A collation is a collection of files that are intended to be displayed and retrieved together. Examples may include pages of a book or document that are spread out across several individual files. If you're intention is to associate files across multiple 'collations', use Tags instead! - -## Entries - -Entries are the representations of your files within the Library. They consist of a reference to the file on your drive, as well as the metadata associated with it. - -### Entry Object Structure (v9): - -- `id`: - - ID for the Entry. - - Int, Unique, Required - - Used for internal processing -- `filename`: - - The filename with extension of the referenced media file. - - String, Required -- `path`: - - The folder path in which the media file is located in. - - String, Required, OS Agnostic -- `fields`: - - A list of Field ID/Value dicts. - - List of dicts, Optional - -NOTE: _Entries currently have several unused optional fields intended for later features._ - -## Tags - -**Tags** are small data objects that represent an attribute of something. A person, place, thing, concept, you name it! Tags in TagStudio allow for more sophisticated Entry organization and searching thanks to their ability to contain alternate names and spellings via `aliases`, relational organization thanks to inherent `subtags`, and more! Tags can be as simple or as powerful as you want to make them, and TagStudio aims to provide as much power to you as possible. - -### Tag Object Structure (v9): - -- `id`: - - ID for the Tag. - - Int, Unique, Required - - Used for internal processing -- `name`: - - The normal name of the Tag, with no shortening or specification. - - String, Required - - Doesn't have to be unique - - Each word analyzed individually - - Used for display, searching, and storing -- `shorthand`: - - The shorthand name for the Tag. - - String, Optional - - Doesn't have to be unique - - Entire string analyzed as-is - - Used for display and searching -- `aliases`: - - Alternate names for the Tag. - - List of Strings, Optional - - Recommended to be unique to this Tag - - Entire string analyzed as-is - - Used for searching -- `subtags`: - - Other Tags that make up properties of this Tag. - - List of Strings, Optional - - Used for display (first subtag only) and searching. -- `color`: - - A hex code value for customizing the Tag's display color - - String, Optional - - Used for display - -### Tag Examples: - -#### League of Legends - -- `name`: "League of Legends" -- `shorthand`: "LoL" -- `aliases`: ["League"] -- `subtags`: ["Game", "Fantasy"] - -#### Arcane - -- `name`: "Arcane" -- `shorthand`: "" -- `aliases`: [] -- `subtags`: ["League of Legends", "Cartoon"] - -#### Jinx (LoL) - -- `name`: "Jinx Piltover" -- `shorthand`: "Jinx" -- `aliases`: ["Jinxy", "Jinxy Poo"] -- `subtags`: ["League of Legends", "Arcane", "Character"] - -#### Zander (Arcane) - -- `name`: "Zander Zanderson" -- `shorthand`: "Zander" -- `aliases`: [] -- `subtags`: ["Arcane", "Character"] - -#### Mr. Legend (LoL) - -- `name`: "Mr. Legend" -- `shorthand`: "" -- `aliases`: [] -- `subtags`: ["League of Legends", "Character"] - -### Query "League of Legends" returns results for: - -- League of Legends [because of "League of Legend"'s name] -- Arcane [because of "Arcane"'s subtag] -- Jinx (LoL) [because of "Jinx Piltover"'s subtag] -- Mr. Legend (LoL) [because of "Mr. Legned (LoL)'s subtag"] -- Zander (Arcane) [because of "Zander Zanderson"'s subtag ("Arcane")'s subtag] - -### Query "LoL" returns results for: - -- League of Legends [because of "League of Legend"'s shorthand] -- LoL [because of "League of Legend"'s shorthand] -- Arcane [because of "Arcane"'s subtag] -- Jinx (LoL) [because of "Jinx Piltover"'s subtag] -- Mr. Legend (LoL) [because of "Mr. Legned (LoL)'s subtag"] -- Zander (Arcane) [because of "Zander Zanderson"'s subtag ("Arcane")'s subtag] - -### Query "Arcane" returns results for: - -- Arcane [because of "Arcane"'s name] -- Jinx (LoL) [because of "Jinx Piltover"'s subtag "Arcane"] -- Zander (Arcane) [because of "Zander Zanderson"'s subtag] - -## Retrieving Entries based on Tag Cluster - -By default when querying Entries, each Entry's `tags` list (stored in the form of Tag `id`s) is compared against the Tag `id`s in a given Tag cluster (list of Tag `id`s) or appended clusters in the case of multi-term queries. The type of comparison depends on the type of query and whether or not it is an inclusive or exclusive query, or a combination of both. This default searching behavior is done in _O(n)_ time, but can be sped up in the future by building indexes on certain search terms. These indexes can be stored on disk and loaded back into memory in future sessions. These indexes will also need to be updated as new Tags and Entries are added or edited. - -## Missing File Resolution - -1. Refresh missing file list (`refresh missing`) (Automatically run if library has few entries) -2. Fix missing files screen (`fix missing`) - -### Fix Missing Files Screen - -0. **Match Search** (Determines if entries can be fixed) Scans for filename in library directory -1. **Quick Fixes** (one match found, no existing entry) -2. **Match Selection** (multiple matches found) -3. **Merge Conflict Resolution** (match has existing entry) - Any remaining missing files can be listed, but they probably really are missing at this point. You can update the path and filename to point to new files if you know where they should actually be pointing to.