Merge pull request #1215 from Zweibach/tags-page

Tags page

docs/faq.md

@@ -4,11 +4,11 @@ title: FAQ
 
 # FAQ
 
-## what is a repository? { id="repositories" }
+## What is a repository? { id="repositories" }
 
 A _repository_ is a service in the hydrus network that stores a certain kind of information--files or tag mappings, for instance--as submitted by users all over the internet. Those users periodically synchronise with the repository so they know everything that it stores. Sometimes, like with tags, this means creating a complete local copy of everything on the repository. Hydrus network clients never send queries to repositories; they perform queries over their local cache of the repository's data, keeping everything confined to the same computer.
 
-## what is a tag? { id="tags" }
+## What is a tag? { id="tags" }
 
 [wiki](https://en.wikipedia.org/wiki/Tag_(metadata))
 
@@ -31,13 +31,13 @@ becomes
 
 'yellow dress'
 
-## what is a namespace? { id="namespaces" }
+## What is a namespace? { id="namespaces" }
 
 A _namespace_ is a category that in hydrus prefixes a tag. An example is 'person' in the tag 'person:ron paul'--it lets people and software know that 'ron paul' is a name. You can create any namespace you like; just type one or more words and then a colon, and then the next string of text will have that namespace.
 
 The hydrus client gives namespaces different colours so you can pick out important tags more easily in a large list, and you can also search by a particular namespace, even creating complicated predicates like 'give all files that do not have any character tags', for instance.
 
-## why not use filenames and folders? { id="filenames" }
+## Why not use filenames and folders? { id="filenames" }
 
 As a retrieval method, filenames and folders are less and less useful as the number of files increases. Why?
 
@@ -52,7 +52,7 @@ So, the client tracks files by their _hash_. This technical identifier easily el
 
 As a general rule, I suggest you not set up hydrus to parse and display all your imported files' filenames as tags. 'image.jpg' is useless as a tag. [Shed the concept of filenames as you would chains.](https://www.youtube.com/watch?v=_yYS0ZZdsnA)
 
-## can the client manage files from their original locations? { id="external_files" }
+## Can the client manage files from their original locations? { id="external_files" }
 
 When the client imports a file, it makes a quickly accessible but human-ugly copy in its internal database, by default under _install\_dir/db/client\_files_. When it needs to access that file again, it always knows where it is, and it can be confident it is what it expects it to be. It never accesses the original again.
 
@@ -71,7 +71,7 @@ It is not unusual for new users who ask for this feature to find their feelings
 
 For this reason, if you are hesitant about doing things the hydrus way, I advise you try running it on a smaller subset of your collection, say 5,000 files, leaving the original copies completely intact. After a month or two, think about how often you used hydrus to look at the files versus navigating through folders. If you barely used the folders, you probably do not need them any more, but if you used them a lot, then hydrus might not be for you, or it might only be for some sorts of files in your collection.
 
-## why use sqlite? { id="sqlite" }
+## Why use SQLite? { id="sqlite" }
 
 Hydrus uses SQLite for its database engine. Some users who have experience with other engines such as MySQL or PostgreSQL sometimes suggest them as alternatives. SQLite serves hydrus's needs well, and at the moment, there are no plans to change.
 
@@ -79,7 +79,7 @@ Since this question has come up frequently, a user has written an excellent docu
 
 [https://gitgud.io/prkc/hydrus-why-sqlite/blob/master/README.md](https://gitgud.io/prkc/hydrus-why-sqlite/blob/master/README.md)
 
-## what is a hash? { id="hashes" }
+## What is a hash? { id="hashes" }
 
 [wiki](https://en.wikipedia.org/wiki/Hash_function)
 
@@ -87,7 +87,7 @@ Hashes are a subject you usually have to be a software engineer to find interest
 
 _For those who_ are _interested: hydrus uses SHA-256, which spits out 32-byte (256-bit) hashes. The software stores the hash densely, as 32 bytes, only encoding it to 64 hex characters when the user views it or copies to clipboard. SHA-256 is not perfect, but it is a great compromise candidate; it is secure for now, it is reasonably fast, it is available for most programming languages, and newer CPUs perform it more efficiently all the time._
 
-## what is an access key? { id="access_keys" }
+## What is an access key? { id="access_keys" }
 
 The hydrus network's repositories do not use username/password, but instead a single strong identifier-password like this:
 
@@ -101,11 +101,11 @@ They are long enough to be impossible to guess, and also randomly generated, so
 
 The access key is the account. Do not give it to anyone you do not want to have access to the account. An administrator will never need it; instead they will want your _account id_.
 
-## what is an account id? { id="account_ids" }
+## What is an account id? { id="account_ids" }
 
 This is another long string of random hexadecimal that _identifies_ your account without giving away access. If you need to identify yourself to a repository administrator (say, to get your account's permissions modified), you will need to tell them your account id. You can copy it to your clipboard in _services->review services_.
 
-## why can my friend not see what I just uploaded? { id="delays" }
+## Why can my friend not see what I just uploaded? { id="delays" }
 
 The repositories do not work like conventional search engines; it takes a short but predictable while for changes to propagate to other users.
 

docs/getting_started_downloading.md

@@ -4,7 +4,7 @@ title: Downloading
 
 # Getting started with downloading
 
-The hydrus client has a sophisticated and completely user-customisable download system. It can pull from any booru or regular gallery site or imageboard, and also from some special examples like twitter and tumblr. A fresh install will by default have support for the bigger sites, but it _is_ possible, with some work, for any user to [create a new shareable downloader](downloader_intro.md) for a new site.
+The hydrus client has a sophisticated and completely user-customisable download system. It can pull from any booru or regular gallery site or imageboard, and also from some special examples like twitter and tumblr. A single file or URL to massive imports, the downloader can handle it all. A fresh install will by default have support for the bigger sites, but it _is_ possible, with some work, for any user to [create a new shareable downloader](downloader_intro.md) for a new site.
 
 The downloader is highly parallelisable, and while the default [bandwidth rules](#bandwidth) should stop you from running too hot and downloading so much at once that you annoy the servers you are downloading from, there are no brakes in the program on what you can get.
 

docs/getting_started_installing.md

@@ -6,13 +6,13 @@ title: Installing and Updating
 
 If any of this is confusing, a simpler guide is [here](https://github.com/Zweibach/text/blob/master/Hydrus/Hydrus%20Help%20Docs/00_tableOfContents.md), and some video guides are [here](https://github.com/CuddleBear92/Hydrus-guides)!
 
-## downloading
+## Downloading
 
 You can get the latest release at [the github releases page](https://github.com/hydrusnetwork/hydrus/releases).
 
 I try to release a new version every Wednesday by 8pm EST and write an accompanying post on [my tumblr](http://hydrus.tumblr.com/) and a Hydrus Network General thread on [8chan.moe /t/](https://8chan.moe/t/catalog.html).
 
-## installing
+## Installing
 
 !!! warning ""
     The hydrus releases are 64-bit only. If you are a python expert, there is the slimmest chance you'll be able to get it running from source on a 32-bit machine, but it would be easier just to find a newer computer to run it on.
@@ -77,7 +77,7 @@ By default, hydrus stores all its data—options, files, subscriptions, _everyth
 !!! info "For macOS users"
     The Hydrus App is **non-portable** and puts your database in `~/Library/Hydrus` (i.e. `/Users/[You]/Library/Hydrus`). You can update simply by replacing the old App with the new, but if you wish to backup, you should be looking at `~/Library/Hydrus`, not the App itself.
 
-## anti-virus { id="anti_virus" }
+## Anti-virus { id="anti_virus" }
 
 Hydrus is made by an Anon out of duct tape and string. It combines file parsing tech with lots of network and database code in unusual and powerful ways, and all through a hacked-together executable that isn't signed by any big official company.
 
@@ -95,7 +95,7 @@ If you are still concerned, please feel free to run from source, as above. You a
 
 In 2022 I am going to explore a different build process to see if that reduces the false positives. We currently make the executable with PyInstaller, which has some odd environment set-up the anti-virus testbeds don't seem to like, and perhaps PyOxidizer will be better. We'll see.
 
-## running
+## Running
 
 To run the client:
 
@@ -113,7 +113,7 @@ To run the client:
     *   Run the 'client' executable in the base directory. You may be able to double-click it, otherwise you are run `./client` from the terminal.
     *   If you experience virtual memory crashes, please review [this thorough guide](Fixing_Hydrus_Random_Crashes_Under_Linux.md) by a user.
 
-## updating
+## Updating
 
 !!! warning
     Hydrus is imageboard-tier software, wild and fun but unprofessional. It is written by one Anon spinning a lot of plates. Mistakes happen from time to time, usually in the update process. There are also no training wheels to stop you from accidentally overwriting your whole db if you screw around. Be careful when updating. Make backups beforehand!
@@ -138,7 +138,7 @@ Releases typically need to update your database to their version. New releases c
 
 Clients and servers of different versions can usually connect to one another, but from time to time, I make a change to the network protocol, and you will get polite error messages if you try to connect to a newer server with an older client or _vice versa_. There is still no _need_ to update the client--it'll still do local stuff like searching for files completely fine. Read my release posts and judge for yourself what you want to do.
 
-## clean installs
+## Clean installs
 
 **This is usually only relevant if you know you have a dll conflict or otherwise update and cannot boot at all.**
 
@@ -155,7 +155,7 @@ However, you need to be careful not to delete your database! It sounds silly, bu
 
 After that, you'll have a 'clean' version of hydrus that only has the latest version's dlls. If hydrus still will not boot, I recommend you roll back to your last working backup and let me, hydrus dev, know what your error is.
 
-## big updates
+## Big updates
 
 If you have not updated in some time--say twenty versions or more--doing it all in one jump, like v250->v290, is likely not going to work. I am doing a lot of unusual stuff with hydrus, change my code at a fast pace, and do not have a ton of testing in place. Hydrus update code often falls to [bitrot](https://en.wikipedia.org/wiki/Software_rot), and so some underlying truth I assumed for the v255->v256 code may not still apply six months later. If you try to update more than 50 versions at once (i.e. trying to perform more than a year of updates in one go), the client will give you a polite error rather than even try.
 
@@ -165,7 +165,7 @@ If you narrow the gap down to just one version and still get an error, please le
 
 _All that said, and while updating is complex and every client is different, one user recently did a giant multi-year update and found this route worked and was efficient: 204 > 238 > 246 > 291 > 328 > 335 > 376 > 421 > 466 > 474_ 
 
-## backing up
+## Backing up
 
 !!! danger "I am not joking around: if you end up liking hydrus, you should back up your database"
 
@@ -197,7 +197,7 @@ I use [ToDoList](http://abstractspoon.com/) to remind me of my jobs for the day,
 
 By default, hydrus stores all your user data in one location, so backing up is simple:
 
-#### the simple way - inside the client
+#### The simple way - inside the client
 :   
     Go _database->set up a database backup location_ in the client. This will tell the client where you want your backup to be stored. A fresh, empty directory on a different drive is ideal.
 
@@ -205,7 +205,7 @@ By default, hydrus stores all your user data in one location, so backing up is s
 
     Advanced users who have migrated their database and files across multiple locations will not have this option--use an external program in this case.
     
-#### the powerful (and best) way - using an external program
+#### The powerful (and best) way - using an external program
 :   
     Doing it yourself is best. If you are an advanced user with a complicated hydrus install migrated across multiple drives, then you will have to do it this way--the simple backup will be disabled.
 
@@ -244,7 +244,7 @@ There is significantly more information about the database structure [here](data
 
 I recommend you always backup before you update, just in case there is a problem with my update code that breaks your database. If that happens, please [contact me](contact.md), describing the problem, and revert to the functioning older version. I'll get on any problems like that immediately.
 
-## backing up with not much space { id="backing_up_small" }
+## Backing up with not much space { id="backing_up_small" }
 
 If you decide not to maintain a backup because you cannot afford drive space for all your files, please please at least back up your actual database files. Use FreeFileSync or a similar program to back up the four 'client*.db' files in install_dir/db when the client is not running. Just make sure you have a copy of those files, and then if your main install becomes damaged, we will have a reference to either roll back to or manually restore data from. Even if you lose a bunch of media files in this case, with an intact database we'll be able to schedule recovery of anything with a URL.
 

docs/getting_started_tags.md

@@ -2,21 +2,22 @@
 title: Tags
 ---
 
-# getting started with tags
+# Getting started with tags
+A _tag_ is a small bit of text describing a single property of something. They make searching easy. Good examples are "flower" or "nicolas cage" or "the sopranos" or "2003". By combining several tags together ( e.g. \[ 'tiger woods', 'sports illustrated', '2008' \] or \[ 'cosplay', 'the legend of zelda' \] ), a huge image collection is reduced to a tiny and easy-to-digest sample.
 
-## how do we find files? { id="intro" }
+## How do we find files? { id="intro" }
 
 So, you have stored some media in your database. Everything is hashed and cached. You can search by inbox and resolution and size and so on, but if you really want to find what we are looking for, you will have to use _tags_.
 
-[FAQ: what is a tag?](faq.md#tags)
+[FAQ: what is a tag?](faq.md#what_is_a_tag)
 
-Your client starts with one local tags service, called 'my tags', which keeps all of its file->tag mappings in your client's database where only you can see them. It is a good place to practise. So, select a file and press F3:
+Your client starts with two [local tags services](getting_started_tags.md#tag_services), called 'my tags' and 'downloader tags' which keeps all of its file->tag mappings in your client's database where only you can see them. It is a good place to practise. So, select a file and press F3:
 
 [![](images/sororitas_local.png)](images/sororitas_local.png)
 
 The autocomplete dropdown in the manage tags dialog works very like the one in a normal search page--you type part of a tag, and matching results will appear below. You select the tag you want with the arrow keys and hit enter. Since your 'my tags' service doesn't have any tags in it yet, you won't get any results here except the exact match of what you typed. If you want to remove a tag, enter the exact same thing again or double-click it in the box above.
 
-Prefixing a tag with a category and a colon will create a _namespaced_ tag. This helps inform the software and other users about what the tag is. Examples of namespaced tags are:
+Prefixing a tag with a category and a colon will create a [_namespaced_ tag](faq.md#what-is-a-namespace). This helps inform the software and other users about what the tag is. Examples of namespaced tags are:
 
 *   `character:batman`
 *   `series:street fighter`
@@ -39,7 +40,30 @@ If you add more tags or system predicates to a search, you will limit the result
 
 You can also exclude a tag by prefixing it with a hyphen (e.g. `-heresy`).
 
-## tag repositories
+## Siblings and parents
+For more in-depth information about them see [siblings](advanced_siblings.md) and [parents](advanced_parents.md).
+
+tl;dr is that siblings lets you chain together different tags that mean the same thing, top sibling in the chain decides what it will look like in lists.  
+Parents lets you virtually add one or more tags (parents) if the 'child' tag is present.
+
+## Tag services
+Hydrus uses services to let you organise tags into various groups as you chose. By default there are two, but you can have however many you want. Some uses are different sets of siblings/parents, tags you don't want to see but still search by, parsing tags into different services based on reliability of the source or the source itself. You could for example parse all tags from Pixiv into one service, Danbooru tags into another, Deviantart etc. and so on as you chose.  
+You are however unable to have less than one.
+
+Services are always local. No tags will accidentally leak or anything like that nor will siblings and parents. So feel free to go wild with whatever odd scheme you want to try out.
+
+Each tag service comes with its own tags, siblings and parents.
+
+### Display rules
+If you go to `tags -> manage where siblings and parents apply` you'll get a window where you can customise where and in what order siblings and parents apply. The service at the top of the list has precedence over all else, then second, and so on depending on how many you have. If you for example have PTR you can use a tag service to overwrite tags/siblings for cases where you disagree with the PTR standards.
+
+### My tags
+The intent is to use this service for tags you yourself want to add.
+
+### Downloader tags
+The default [tag parse target](getting_started_downloading.md#parsing). Tags of things you download will end up here unless you change the settings. It's probably a good idea to set up some tag blacklists for tags you don't want.
+
+## Tag repositories
 
 It can take a long time to tag even small numbers of files well, so I created _tag repositories_ so people can share the work.
 
@@ -69,4 +93,4 @@ I recommend you not spam tags to the public tag repo until you get a rough feel
 
 You can connect to more than one tag repository if you like. When you are in the _manage tags_ dialog, pressing the up or down arrow keys on an empty input switches between your services.
 
-[FAQ: why can my friend not see what I just uploaded?](faq.md#delays)
+[FAQ: why can my friend not see what I just uploaded?](faq.md#delays)