Begin converting docs to markdown for MkDocs

.gitignore

@@ -48,4 +48,5 @@ db/*.log
 db/*.conf
 db/client_files/
 db/server_files/
-db/missing_and_invalid_files/
+db/missing_and_invalid_files/
+site/

docs/PTR.md

@@ -0,0 +1,94 @@
+# PTR for Dummies
+or *Myths and facts about the Public Tag Repository*
+
+## What is the PTR?  
+Short for <b>P</b>ublic  <b>T</b>ag <b>R</b>epository, a now community managed repository of tags. Locally it acts as a tag service, just like `my tags`. At the time of writing 54 million files have tags on it. The PTR only store the sha256 hash and tag mappings of a file, not the files themselves or any non-tag meta data. In other words: If you don not see it in the tag list then it is not stored.
+
+Most of the things in this document also applies to [self-hosted servers](https://hydrusnetwork.github.io/hydrus/help/server.html), except for tag guidelines.
+
+## Connecting to the PTR
+The easiest method is to use the built in function, found under `help -> add the public tag repository`. For adding it manually, if you so desire, read the Hydrus help document on [access keys](https://hydrusnetwork.github.io/hydrus/help/access_keys.html).  
+If you are starting out completely fresh you can also download a fully synced client [here](https://koto.reisen/quicksync/). Though possibly a bit (couple of days or so usually) out of date it will none the less save time. Some settings may differ from the defaults of an official installation.  
+Once you are connected Hydrus will proceed to download and then process the update files. The progress of this can be seen under `services -> review services -> remote -> tag repositories -> public tag repository`. Here you can view its status, your account (the default account is a shared public account. Currently only janitors and the administrator have personal accounts), tag status, and how synced you are. Being behind on the sync by a certain amount makes you unable to push tags and petitions until you are caught up again.
+
+## How does it work?
+For something to end up on the PTR it has to be pushed there. Tags can either be entered into the tag service manually by the user through the `manage tags` window, or be routed there by a parser when downloading files. See [parsing tags](https://hydrusnetwork.github.io/hydrus/help/getting_started_downloading.html). Once tags have been entered into the PTR tag service they are pending until pushed. This is indicated by the `pending ()` that will appear between `tags` and `help` in the menu bar. Here you can chose to either push your changes to the PTR or discard them.
+
+- Adding tags pass automatically.
+- Deleting (petitioning) tags requires janitor action.
+- If a tag has been deleted from a file it will not be added again.
+- Currently there is no way for a normal user to re-add a deleted tag. If it gets deleted then it is gone. A janitor can undelete tags manually.
+- Adding and petitioning siblings and parents all require janitor action.
+- The client always assumes the server approves any petition. If your petition gets rejected you wont know.
+
+When making petitions it is important to remember that janitors are only human. We do not necessarily know everything about every niche. We do not necessarily have the files you are making changes for and we will only see a blank thumbnail if we do not have the file. Explain why you are making a petition. Try and keep the number of files manageable. If a janitor at any point is unsure if the petition is correct they are likely to deny the entire petition rather than risk losing good tags. Some users have pushed changes regarding hundreds of tags over thousands of files at once, but due to disregarding PTR tagging practices or being lazy with justification the petition has been denied entirely. Or they have just been plain wrong, trying to impose frankly stupid tagging methods.
+
+Furthermore, if you are two weeks out of sync with PTR you are unable to push additions or deletions until you're back within the threshold.
+
+---
+
+Q: Does this automagically tag my files?
+:   A: No. Until we get machine learning based auto-tagging nothing is truly automatic. All tags on the PTR were uploaded by another user, so if nobody uploaded tags associated with the hash of your file it won't have any tags in the PTR.
+
+Q: How good is the PTR at tagging [insert file format or thing from site here]?
+:   A: That depends largely on if there's a scrapable database of tags for whatever you're asking about. Anything that comes from a booru or site that supports tags is fairly likely to have something on the PTR. Original content on some obscure chan-style imageboard is less so.
+
+Q: Help! My files don't have any tags! What do!?
+:   A: As stated above, some things are just very likely to not have any tags. It is also possible that the files have been altered by whichever service you downloaded from. Imgur, Reddit, Discord, and many other sites and services recompress images to save space which might give it a different hash even if it looks indistinguishable from the original file. Use one of the IQDB lookup programs linked in [Cuddle's wiki](https://github.com/CuddleBear92/Hydrus-Presets-and-Scripts/wiki/0-Hydrus-Apps-and-Scripts).
+
+Q: Why is my database so big!? This can't be right. 
+:   A: It is working as intended. The size is because you are literally downloading and processing the entire tag database and history of the PTR. It is done this way to ensure redundancy and privacy. Redundancy because anybody with an up-to-date PTR sync can just start their own. Privacy because nobody can tell what files you have since you are downloading the tags for everything the PTR has.
+
+Q: Does that mean I can't do anything about the size? 
+:   A: Correct. There are some plans to crunch the size through a few methods but there are a lot of other far more requested features being, well, requested. Speaking crassly if you are bothered by the size requirement of the PTR you probably don't have a big enough library to really benefit and would be better of just using the IQDB script.
+
+---
+
+## Janitors
+Janitors are the people that review petitions. You can meet us at the community [Discord](https://discord.gg/3H8UTpb) to ask questions or see us bitch about some of the silly stuff boorus and users cause to end up in the PTR.
+
+## Tag Guidelines
+
+These are a mix of standard practice used by various boorus and changes made by Hydrus Developer and PTR users, ratified by the janitors that actually have to manage all of this. The "full" document is viewable at [Cuddle's git repo](https://raw.githubusercontent.com/CuddleBear92/Hydrus-Presets-and-Scripts/master/tag%20guidelines). See Hydrus Developer's [thoughts on a public tagging schema](https://hydrusnetwork.github.io/hydrus/help/tagging_schema.html).
+
+If you are looking to help out by tagging low tag-count files, remember to keep the tags objective, start simple by for example adding the characters/persons and big obvious things in the image or what else. Tagging every little thing and detail is a sure path to burnout.  
+If you are looking to petition removal of tags then it is preferable to sibling common misspellings, underscores, and defunct tags rather than deleting them outright. The exception is for ambiguous tags where it is better to delete and replace with a less ambiguous tag. When deleting tags that don't belong in the image it can be helpful if you include a short description as to why.  
+It's also helpful if you sanitise downloaded tags from sites with tagged galleries before pushing them to the PTR. For example Pixiv, where you can have a gallery of multiple images, each containing one character, and all of the characters being tagged. Consequently all images in that gallery will have all of the character tags despite no image having more than one character.
+
+### Siblings and parents
+When making siblings, go for the closest less-bad tag. Example: `bad_tag` -> `bad tag`, rather than going for what the top level sibling might be. This creates less potential future work in case standards change and makes it so your request is less likely to be denied by a janitor not being entirely certain that what you're asking is right. Be careful about creating siblings for potentially ambiguous tags. Is `james bond` supposed to be `character:james bond` or is it `series:james bond`? This is a bit of a bad example due to having the case of the character always belonging to the series, so you can safely sibling it to `series:james bond` since all instances of the character will also have the series, but not all instances of the series will have the character. So let us look at another example: how about `wool`? Is it the material harvested from sheep, or is it the Malaysian artist that likes to draw Touhou? In doubtful cases it's better to leave it as is, petition the tag for deletion if it's incorrect and add the correct tag.
+
+When making parents, make sure it's an always factually correct relationship. `character:james bond` always belongs to `series:james bond`. But `character:james bond` is not always `person:pierce brosnan`. Common examples of not-always true relationships: gender (genderbending), species (furrynisation/humanisation/anthropomorphism), hair colour, eye colour, and other mutable traits.
+
+### Namespaces
+`creator:`
+:   Used for the creator of the tagged piece of media. Hydrus being primarily used for images it will often be the artist that drew the image. Other potential examples are the author of a book or musician for a song.  
+
+`character:`
+:   Refers to characters. James Bond is a character.  
+
+`person:`
+:   Refers to real persons. Pierce Brosnan is a person.  
+
+`series:`
+:   Used for series. *James Bond* is a series tag and so is *GoldenEye*. Due to usage being different on some boorus chance is that you will also see things like Absolut Vodka and other brands in it.  
+
+`photoset:`
+:   Used for photosets. Primarily seen for content from idols, cosplayers, and gravure idols. 
+
+`studio:`
+:   Is used for the entity that facilitated the production of the file or what's in it. Eon Productions for the *James Bond* movies.  
+
+`species:`
+:   Species of the depicted characters/people/animals. Somewhat controversial for being needlessly detailed, some janitors not liking the namespace at all. Primarily used for furry content.  
+
+`title:`
+:   The title of the file. One of the tags Hydrus uses for various purposes such as sorting and collecting. Somewhat tainted by rampant Reddit parsers.
+
+`medium:`
+:   Used for tags about the image and how it's made. Photography, water painting, napkin sketch as a few examples. White background, simple background, checkered background as a few others. **What you see about the image.**  
+
+`meta:`
+:   This namespace is used for information that isn't visible in the image itself or where you might need to go to the source. Some examples include: third-party edit, paid reward (patreon/enty/gumroad/fantia/fanbox), translated, commentary, and such. **What you know about the image.**
+
+Namespaces not listed above are not "supported" by the janitors and are liable to get siblinged out, removed, and/or mocked if judged being bad and annoying enough to justify the work. Do not take this to mean that all un-listed namespaces are bad, some are created and used by parsers to indicate where an image came from which can be helpful if somebody else wants to fetch the original or check source tags against the PTR tags. But do exercise some care in what you put on the PTR if you use custom namespaces. Recently `clothing:` was removed due to being disliked, no booru using it, and the person(s) pushing for it seeming to have disappeared, leaving a less-than-finished mess behind. It was also rife with lossy siblings and things that just plain don't belong with clothing, such as `clothing:brown hair`.

docs/access_keys.md

@@ -0,0 +1,69 @@
+---
+title: PTR access keys
+---
+
+The PTR is now run by users with more bandwidth than I had to give, so the bandwidth limits are gone! If you would like to talk with the new management, please check the [discord](https://discord.gg/wPHPCUZ).
+
+A guide and schema for the new PTR is [here](https://github.com/Zweibach/text/blob/master/Hydrus/PTR.md).
+
+## first off
+
+I don't like it when programs I use connect anywhere without asking me, so I have purposely not pre-baked any default repositories into the client. You have to choose to connect yourself. **The client will never connect anywhere until you tell it to.**
+
+For a long time, I ran the Public Tag Repository myself and was the lone janitor. It grew to 650 million tags, and siblings and parents were just getting complicated, and I no longer had the bandwidth or time it deserved. It is now run by users.
+
+There also used to be just one user account that everyone shared. Everyone was essentially the same Anon, and all uploads were merged to that one ID. As the PTR became more popular, and more sophisticated and automatically generated content was being added, it became increasingly difficult for the janitors to separate good submissions from bad and undo large scale mistakes.
+
+That old shared account is now a 'read-only' account. This account can only download--it cannot upload new tags or siblings/parents. Users who want to upload now generate their own individual accounts, which are still Anon, but separate, which helps janitors approve and deny uploaded petitions more accurately and efficiently.
+
+I recommend using the shared read-only account, below, to start with, but if you decide you would like to upload, making your own account is easy--just click the 'check for automatic account creation' button in _services->manage services_, and you should be good. You can change your access key on an existing service--you don't need to delete and re-add or anything--and your client should quickly resync and recognise your new permissions.
+
+## privacy
+
+I have tried very hard to ensure the PTR respects your privacy. Your account is a very barebones thing--all a server stores is a couple of random hexadecimal texts and which rows of content you uploaded, and even the memory of what you uploaded is deleted after a delay. The server obviously needs to be aware of your IP address to accept your network request, but it forgets it as soon as the job is done. Normal users are never told which accounts submitted any content, so the only privacy implications are against janitors or (more realistically, since the janitor UI is even more buggy and feature-poor than the hydrus front-end!) the server owner or anyone else with raw access to the server as it operates or its database files.
+
+Most users should have very few worries about privacy. The general rule is that it is always healthy to use a VPN, but please check [here for a full discussion and explanation of the anonymisation routine](privacy.html).
+
+## a note on resources
+
+!!! danger
+	**If you are on an HDD, or your SSD does not have at least 64GB of free space, do not add the PTR!**
+
+The PTR has been operating since 2011 and is now huge, more than a billion mappings! Your client will be downloading and indexing them all, which is currently (2021-06) about 6GB of bandwidth and 50GB of hard drive space. It will take _hours_ of total processing time to catch up on all the years of submissions. Furthermore, because of mechanical drive latency, HDDs are too slow to process all the content in reasonable time. Syncing is only recommended if your [hydrus db is on an SSD](database_migration.html). Even then, it is healthier and allows the client to 'grow into' the PTR if the work is done in small pieces in the background, either during idle time or shutdown time, rather than trying to do it all at once. Just leave it to download and process on its own--it usually takes a couple of weeks to quietly catch up. You'll see tags appear on your files as it proceeds, first on older, then all the way up to new files just uploaded a couple days ago. Once you are synced, the daily processing work to stay synced is usually just a few minutes. If you leave your client on all the time in the background, you'll likely never notice it.
+
+## easy setup
+
+Hit _help->add the public tag repository_ and you will all be set up.
+
+## manually
+
+Hit _services->manage services_ and click _add->hydrus tag repository_. You'll get a panel, fill it out like this:
+
+![](images/edit_repos_public_tag_repo.png)
+
+Here's the info so you can copy it:
+
+
+``` title="address"
+ptr.hydrus.network
+```
+``` title="port"
+45871
+```
+``` title="access key"
+4a285629721ca442541ef2c15ea17d1f7f7578b0c3f4f5f2a05f8f0ab297786f
+```
+
+Note that because this is the public shared key, you can ignore the '<span class="hydrus-warning">DO NOT SHARE</span>' red text warning.
+
+It is worth checking the 'test address' and 'test access key' buttons just to double-check your firewall and key are all correct. Notice the 'check for automatic account creation' button, for if and when you decide you want to contribute to the PTR.
+
+Then you can check your PTR at any time under _services->review services_, under the 'remote' tab:
+
+![](images/review_repos_public_tag_repo.png)
+
+## jump-starting an install
+
+A user kindly manages a store of update files and pre-processed empty client databases to get your synced quicker. This is generally recommended for advanced users or those following a guide, but if you are otherwise interested, please check it out:
+
+[https://cuddlebear92.github.io/Quicksync/](https://cuddlebear92.github.io/Quicksync/)

docs/assets/hydrus-black.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="2" clip-rule="evenodd" viewBox="0 0 688 934"><path fill-rule="nonzero" d="M301.334 0v678.8l-6.267-.8c-15.2-1.734-19.067-2.4-30.4-4.934-47.467-10.533-79.467-35.466-96-74.666-4.133-9.6-8.8-24.267-10.8-33.467-2.4-10.933-4.667-23.733-5.333-29.467-.4-3.733-1.067-8.266-1.334-10.133-1.866-10.667-2.533-52.267-2.533-171.6V220H0v25.333l3.734.8c24.666 5.467 41.2 17.067 46.666 32.8 6 17.067 7.2 31.334 7.734 89.734.933 93.2 1.733 145.199 2.4 149.999.266 2.534.933 7.6 1.333 11.334 1.067 8 2.8 18.266 5.6 33.466.267 1.467 2.4 9.067 4.667 16.667 18 60.667 52.533 98.267 110.666 120.533 29.467 11.334 72 18.534 114.267 19.2l4.267.134v213.333h85.333V720l3.066-.134c15.6-.666 32.534-1.866 44.934-3.2 28.8-3.333 58.666-12 84.666-24.666 50.667-24.934 82-65.867 98-128.134 1.6-6.133 3.2-12.666 3.467-14.533.4-1.867 1.2-6.4 1.867-10 .666-3.733 1.6-9.333 2-12.667.533-3.333 1.066-7.866 1.466-10 2-14.133 2.534-32 3.867-150.666.267-30.8.8-57.867 1.2-60 .267-2.267 1.067-7.333 1.467-11.333 3.2-25.6 12.8-36.134 42-45.734l12.666-4.266L687.2 234c-.133-5.867-.267-11.467-.4-12.4-.133-1.333-15.333-1.6-73.733-1.333l-73.6.4L539.333 358c-.133 75.467-.666 142.4-1.2 148.666-2.133 23.067-2.666 27.067-4.933 40.667-.8 4.4-1.733 9.467-2 11.333-1.2 6.267-7.2 27.334-9.733 34.134-7.6 19.6-15.067 31.6-28 44.266-19.067 18.8-42.534 29.734-80.134 37.467-6.933 1.333-15.866 2.933-19.6 3.333l-7.066.8V0h-85.333z"/></svg>

docs/assets/hydrus-white.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" stroke-linejoin="round" stroke-miterlimit="2" clip-rule="evenodd" viewBox="0 0 688 934"><path fill="#fff" fill-rule="nonzero" d="M301.334 0v678.8l-6.267-.8c-15.2-1.734-19.067-2.4-30.4-4.934-47.467-10.533-79.467-35.466-96-74.666-4.133-9.6-8.8-24.267-10.8-33.467-2.4-10.933-4.667-23.733-5.333-29.467-.4-3.733-1.067-8.266-1.334-10.133-1.866-10.667-2.533-52.267-2.533-171.6V220H0v25.333l3.734.8c24.666 5.467 41.2 17.067 46.666 32.8 6 17.067 7.2 31.334 7.734 89.734.933 93.2 1.733 145.199 2.4 149.999.266 2.534.933 7.6 1.333 11.334 1.067 8 2.8 18.266 5.6 33.466.267 1.467 2.4 9.067 4.667 16.667 18 60.667 52.533 98.267 110.666 120.533 29.467 11.334 72 18.534 114.267 19.2l4.267.134v213.333h85.333V720l3.066-.134c15.6-.666 32.534-1.866 44.934-3.2 28.8-3.333 58.666-12 84.666-24.666 50.667-24.934 82-65.867 98-128.134 1.6-6.133 3.2-12.666 3.467-14.533.4-1.867 1.2-6.4 1.867-10 .666-3.733 1.6-9.333 2-12.667.533-3.333 1.066-7.866 1.466-10 2-14.133 2.534-32 3.867-150.666.267-30.8.8-57.867 1.2-60 .267-2.267 1.067-7.333 1.467-11.333 3.2-25.6 12.8-36.134 42-45.734l12.666-4.266L687.2 234c-.133-5.867-.267-11.467-.4-12.4-.133-1.333-15.333-1.6-73.733-1.333l-73.6.4L539.333 358c-.133 75.467-.666 142.4-1.2 148.666-2.133 23.067-2.666 27.067-4.933 40.667-.8 4.4-1.733 9.467-2 11.333-1.2 6.267-7.2 27.334-9.733 34.134-7.6 19.6-15.067 31.6-28 44.266-19.067 18.8-42.534 29.734-80.134 37.467-6.933 1.333-15.866 2.933-19.6 3.333l-7.066.8V0h-85.333z"/></svg>

docs/assets/stylesheets/extra.css

@@ -0,0 +1,7 @@
+.spoiler:not(:hover) {
+  color: #000;
+  background-color: #000;
+}
+.hydrus-warning {
+  color: #d00;
+}

docs/getting_started_downloading.md

@@ -0,0 +1,119 @@
+---
+title: downloading
+---
+
+# getting started with downloading
+
+## 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 for a new site.
+
+The downloader is highly parallelisable, and while the default bandwidth rules 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.
+
+!!! danger
+    It is very important that you take this slow. Many users get overexcited with their new ability to download 500,000 files _and then do so_, only discovering later that 98% of what they got was junk that they now have to wade through. Figure out what workflows work for you, how fast you process files, what content you _actually_ want, how much bandwidth and hard drive space you have, and prioritise and throttle your incoming downloads to match. If you can realistically only archive/delete filter 50 files a day, there is little benefit to downloading 500 new files a day. START SLOW.
+
+It also takes a decent whack of CPU to import a file. You'll usually never notice this with just one hard drive import going, but if you have twenty different download queues all competing for database access and individual 0.1-second hits of heavy CPU work, you will discover your client starts to judder and lag. Keep it in mind, and you'll figure out what your computer is happy with. I also recommend you try to keep your total loaded files/urls to be under 20,000 to keep things snappy. Remember that you can pause your import queues, if you need to calm things down a bit.
+
+## let's do it
+
+Open the new page selector with F9 and then hit _download->gallery_:
+
+![](images/downloader_page.png)
+
+The gallery page can download from multiple sources at the same time. Each entry in the list represents a basic combination of two things:
+
+**source**
+:   The site you are getting from. Safebooru or Danbooru or Deviant Art or twitter or anywhere else.
+
+**query text**
+:   Something like 'contrapposto' or 'blonde\_hair blue\_eyes' or an artist name like 'incase'. Whatever is searched on the site to return a list of ordered media.
+
+So, when you want to start a new download, you first select the source with the button and then type in a query in the text box and hit enter. The download will soon start and fill in information, and thumbnails should stream in, just like the hard drive importer. The downloader typically works by walking through the search's gallery pages one by one, queueing up the found files for later download. There are several intentional delays built into the system, so do not worry if work seems to halt for a little while--you will get a feel for hydrus's 'slow persistent growth' style with experience.
+
+Do a test download now, for fun! Pause its gallery search after a page or two, and then pause the file import queue after a dozen or so files come in.
+
+The thumbnail panel can only show results from one queue at a time, so double-click on an entry to 'highlight' it, which will show its thumbs and also give more detailed info and controls in the 'highlighted query' panel. I encourage you to explore the highlight panel over time, as it can show and do quite a lot. Double-click again to 'clear' it.
+
+It is a good idea to 'test' larger downloads, either by visiting the site itself for that query, or just waiting a bit and reviewing the first files that come in. Just make sure that you _are_ getting what you thought you would, whether that be verifying that the query text is correct or that the site isn't only giving you bloated gifs or other bad quality files. The 'file limit', which stops the gallery search after the set number of files, is also great for limiting fishing expeditions (such as overbroad searches like 'wide_hips', which on the bigger boorus have 100k+ results and return _variable_ quality). If the gallery search runs out of new files before the file limit is hit, the search will naturally stop (and the entry in the list should gain a ⏹ 'stop' symbol).
+
+_Note that some sites only serve 25 or 50 pages of results, despite their indices suggesting hundreds. If you notice that one site always bombs out at, say, 500 results, it may be due to a decision on their end. You can usually test this by visiting the pages hydrus tried in your web browser._
+
+**In general, particularly when starting out, artist searches are best.** They are usually fewer than a thousand files and have fairly uniform quality throughout.
+
+## parsing tags
+
+But we don't just want files--most sites offer tags as well. By default, hydrus now starts with a local tag service called 'downloader tags' and it will parse (get) all the tags from normal gallery sites and put them in this service. You don't have to do anything, you will get some decent tags. As you use the client, you will figure out which tags you like and where you want them. On the downloader page, click _tag import options_:
+
+![](images/tag_import_options_default.png)
+
+This is an important dialog, although you will not need to use it much. It governs which tags are parsed and where they go. To keep things easy to manage, a new downloader will refer to the 'default' tag import options for a website, but for now let's set some values just for this downloader:
+
+![](images/tag_import_options_specific.png)
+
+You can see that each tag service on your client has a separate section. If you add the PTR, that will get a new box too. A new client is set to _get all tags_ for 'downloader tags' service. Things can get much more complicated. Have a play around with the options here as you figure things out. Most of the controls have tooltips or longer explainers in sub-dialogs, so don't be afraid to try things.
+
+It is easy to get tens of thousands of tags by downloading this way. Different sites offer different kinds and qualities of tags, and the client's downloaders (which were designed by me, the dev, or a user) may parse all or only some of them. Many users like to just get everything on offer, but others only ever want, say, 'creator', 'series', and 'character' tags. If you feel brave, click that 'all tags' button, which will take you into hydrus's advanced 'tag filter', which allows you to select which of the incoming list of tags will be added.
+
+The blacklist button will let you skip downloading files that have certain tags (perhaps you would like to auto-skip all images with 'gore', 'scat', or 'diaper'?), again using the tag filter, while the whitelist enables you to only allow files that have at least one of a set of tags. The 'additional tags' adds some fixed personal tags to all files coming in--for instance, you might like to add 'process into favourites' to your 'my tags' for some query you really like so you can find those files again later and process them separately. That little 'cog' icon button can also do some advanced things.
+
+To edit the defaults, hit up _network->downloaders->manage default tag import options_. You should do this as you get a better idea of your preferences. You can set them for all file posts generally, all watchers, and for specific sites as well.
+
+
+!!! warning
+    The file limit and file/tag import options on the upper panel, if changed, will only apply to **new** queries. If you want to change the options for an existing queue, either do so on its highlight panel below or use the 'set options to queries' button.
+
+## watching threads
+
+If you are an imageboard user, try going to a thread you like and drag-and-drop its URL (straight from your web browser's address bar) onto the hydrus client. It should open up a new 'watcher' page and import the thread's files!
+
+![](images/watcher_page.png)
+
+With only one URL to check, watchers are a little simpler than gallery searches, but as that page is likely receiving frequent updates, it checks it over and over until it dies. By default, the watcher's 'checker options' will regulate how quickly it checks based on the speed at which new files are coming in--if a thread is fast, it will check frequently; if it is running slow, it may only check once per day. When a thread falls below a critical posting velocity or 404s, checking stops.
+
+In general, you can leave the checker options alone, but you might like to revisit them if you are always visiting faster or slower boards and find you are missing files or getting DEAD too early.
+
+## bandwidth
+
+It will not be too long until you see a "bandwidth free in xxxxx..." message. As a long-term storage solution, hydrus is designed to be polite in its downloading--both to the source server and your computer. The client's default bandwidth rules have some caps to stop big mistakes, spread out larger jobs, and at a bare minimum, no domain will be hit more than once a second.
+
+All the bandwidth rules are completely customisable. They can get quite complicated. I **strongly** recommend you not look for them until you have more experience. I **especially strongly** recommend you not ever turn them all off, thinking that will improve something, as you'll probably render the client too laggy to function and get yourself an IP ban from the next server you pull from.
+
+If you want to download 10,000 files, set up the queue and let it work. The client will take breaks, likely even to the next day, but it will get there in time. Many users like to leave their clients on all the time, just running in the background, which makes these sorts of downloads a breeze--you check back in the evening and discover your download queues, watchers, and subscriptions have given you another thousand things to deal with.
+
+Again: the real problem with downloading is not finding new things, it is keeping up with what you get. Start slow and figure out what is important to your bandwidth budget, hard drive budget, and free time budget. <span class="spoiler">Almost everyone fails at this.</span>
+
+## subscriptions
+
+Subscriptions are a way to automatically recheck a good query in future, to keep up with new files. Many users come to use them. When you are comfortable with downloaders and have an idea of what you like, come back and read the subscription help, which is [here](getting_started_subscriptions.html).
+
+## other downloading
+
+There are two other ways of downloading, mostly for advanced or one-off use.
+
+The **url downloader** works like the gallery downloader but does not do searches. You can paste downloadable URLs to it, and it will work through them as one list. Dragging and dropping recognisable URLs onto the client (e.g. from your web browser) will also spawn and use this downloader.
+
+The **simple downloader** will do very simple parsing for unusual jobs. If you want to download all the images in a page, or all the image link destinations, this is the one to use. There are several default parsing rules to choose from, and if you learn the downloader system yourself, it will be easy to make more.
+
+## logins
+
+The client now supports a flexible (but slightly prototype and ugly) login system. It can handle simple sites and is as completely user-customisable as the downloader system. The client starts with multiple login scripts by default, which you can review under _network->downloaders->manage logins_:
+
+![](images/manage_logins.png)
+
+Many sites grant all their content without you having to log in at all, but others require it for NSFW or special content, or you may wish to take advantage of site-side user preferences like personal blacklists. If you wish, you can give hydrus some login details here, and it will try to login--just as a browser would--before it downloads anything from that domain.
+
+!!! warning
+    For multiple reasons, I do not recommend you use important accounts with hydrus. Use a throwaway account you don't care much about.
+
+To start using a login script, select the domain and click 'edit credentials'. You'll put in your username/password, and then 'activate' the login for the domain, and that should be it! The next time you try to get something from that site, the first request will wait (usually about ten seconds) while a login popup performs the login. Most logins last for about thirty days (and many refresh that 30-day timer every time you make a new request), so once you are set up, you usually never notice it again, especially if you have a subscription on the domain.
+
+Most sites only have one way of logging in, but hydrus does support more. Hentai Foundry is a good example--by default, the client performs the 'click-through' login as a guest, which requires no credentials and means any hydrus client can get any content from the start. But this way of logging in only lasts about 60 minutes or so before having to be refreshed, and it does not hide any spicy stuff, so if you use HF a lot, I recommend you create a throwaway account, set the filters you like in your HF profile (e.g. no guro content), and then click the 'change login script' in the client to the proper username/pass login.
+
+The login system is new and still a bit experimental. Don't try to pull off anything too weird with it! If anything goes wrong, it will likely delay the script (and hence the whole domain) from working for a while, or invalidate it entirely. If the error is something simple, like a password typo or current server maintenance, go back to this dialog to fix and scrub the error and try again. If the site just changed its layout, you may need to update the login script. If it is more complicated, please contact me, hydrus_dev, with the details!
+
+If you would like to login to a site that is not yet supported by hydrus (usually ones with a Captcha in the login page), see about getting a web browser add-on that lets you export a cookies.txt (either for the whole browser or just for that domain) and then drag and drop that file onto the hydrus _network->data->review session cookies_ dialog. This sometimes does not work if your add-on's export formatting is unusual. If it does work, hydrus will import and use those cookies, which skips the login by making your hydrus pretend to be your browser directly. This is obviously advanced and hacky, so if you need to do it, let me know how you get on and what tools you find work best!
+
+[Read about ratings --->](getting_started_ratings.html)
+
+[Go back to the index --->](index.html)

docs/getting_started_files.md

@@ -0,0 +1,147 @@
+---
+title: files
+---
+
+# getting started with files
+
+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)!
+
+!!! warning
+
+	Hydrus can be powerful, and you control everything. By default, you are not connected to any servers and absolutely nothing is shared with other users--and you can't accidentally one-click your way to exposing your whole collection--but if you tag private files with real names and click to upload that data to a tag repository that other people have access to, the program won't try to stop you. If you want to do private sexy slideshows of your shy wife, that's great, but think twice before you upload files or tags anywhere, particularly as you learn. It is **impossible** to contain leaks of private information.
+
+	There are no limits and few brakes on your behaviour. It is possible to import millions of files. For many new users, their first mistake is downloading too much too fast in overexcitement and becoming overwhelmed. Take things slow and figure out good processing workflows that work for your schedule before you start adding 500 subscriptions.
+
+## the problem
+
+If you have ever seen something like this--
+
+![](images/pictures.png "After a while, I started just dropping everything in here unsorted. It would only grow, hungry and untouchable.")
+
+--then you already know the problem: using a filesystem to manage a lot of images sucks.
+
+Finding the right picture quickly can be difficult. Finding everything by a particular artist at a particular resolution is unthinkable. Integrating new files into the whole nested-folder mess is a further pain, and most operating systems bug out when displaying 10,000+ thumbnails.
+
+## so, what does the hydrus client do?
+
+Let's first focus on _importing_ files.
+
+When you first boot the client, you will see a blank page. There are no files in the database and so there is nothing to search. To get started, I suggest you simply drag-and-drop a folder with a hundred or so images onto the main window. A dialog will appear affirming what you want to import. Ok that, and a new page will open. Thumbnails will stream in as the software processes each file.
+
+[![](images/import.png)](images/import.png)
+
+The files are being imported into the client's database. [The client discards their filenames.](faq.html#filenames)
+
+Notice your original folder and its files are untouched. You can move the originals somewhere else, delete them, and the client will still return searches fine. In the same way, you can delete from the client, and the original files will remain unchanged--import is a **copy**, not a move, operation. The client performs all its operations on its internal database, which holds copies of the files it imports. If you find yourself enjoying using the client and decide to completely switch over, you can delete the original files you import without worry. You can always export them back again later.
+
+[FAQ: can the client manage files from their original locations?](faq.html#external_files)
+
+Now:
+
+*   Click on a thumbnail; it'll show in the preview screen, bottom left.
+*   Double- or middle-click the thumbnail to open the media viewer. You can hit ++f++ to switch between giving the fullscreen a frame or not. You can use your scrollwheel or page up/down to browse the media and ctrl+scrollwheel to zoom in and out.
+*   Move your mouse to the top-left, top-middle and top-right of the media viewer. You should see some 'hover' panels pop into place.
+    
+    ![](images/hover_command.png)
+    
+    The one on the left is for tags, the middle is for browsing and zoom commands, and the right is for status and ratings icons. You will learn more about these things as you get more experience with the program.
+    
+*   Press ++enter++ or double/middle-click again to close the media viewer.
+*   You can quickly select multiple files by shift- or ctrl- clicking. Notice how the status bar at the bottom of the screen updates with the number selected and their total size. Right-clicking your selection will present another summary and many actions.
+*   Hit ++f9++ to bring up a new page chooser. You can navigate it with the arrow keys, your numpad, or your mouse.
+*   On the left of a normal search page is a text box. When it is focused, a dropdown window appears. It looks like this:
+    
+    ![](images/ac_dropdown_system.png)
+    
+    This is where you enter the predicates that define the current search. If the text box is empty, the dropdown will show 'system' tags that let you search by file metadata such as file size or animation duration. To select one, press the up or down arrow keys and then enter, or double click with the mouse.
+    
+    When you have some tags in your database, typing in the text box will search them:
+    
+    ![](images/ac_dropdown_feel.png)
+    
+    The (number) shows how many files have that tag, and hence how large the search result will be if you select that tag.
+    
+    Clicking 'searching immediately' will pause the searcher, letting you add several tags in a row without sending it off to get results immediately. Ignore the other buttons for now--you will figure them out as you gain experience with the program.
+    
+*   You can remove from the list of 'active tags' in the box above with a double-click, or by entering the exact same tag again through the dropdown.
+*   Play with the system tags more if you like, and the sort-by dropdown. The collect-by dropdown is advanced, so wait until you understand _namespaces_ before expecting it to do anything.
+*   To close a page, middle-click its tab.
+
+The client can currently import the following mimetypes:
+
+*   **image/bmp** (.bmp - converted to image/png on import)
+*   **image/gif** (.gif)
+*   **image/png** (.png)
+*   **image/apng** (.apng)
+*   **image/jpeg** (.jpg)
+*   **image/tiff** (.tiff)
+*   **image/webp** (.webp)
+*   **video/x-msvideo** (.avi)
+*   **video/x-flv** (.flv)
+*   **video/x-matroska** (.mkv)
+*   **video/quicktime** (.mov)
+*   **video/mp4** (.mp4)
+*   **video/mpeg** (.mpeg)
+*   **video/webm** (.webm)
+*   **video/x-ms-wmv** (.wmv)
+*   **audio/mp3** (.mp3)
+*   **audio/ogg** (.ogg)
+*   **audio/flac** (.flac)
+*   **audio/x-ms-wma** (.wma)
+*   **application/x-shockwave-flash** (.swf)
+*   **application/pdf** (.pdf)
+*   **application/x-photoshop** (.psd)
+*   **application/clip** (.clip)
+*   **application/vnd.rar** (.rar)
+*   **application/zip** (.zip)
+*   **application/x-7z-compressed** (.7z)
+
+Although some support is imperfect for the complicated filetypes. For the Windows and Linux built releases, hydrus now embeds an MPV player for video, audio and gifs, which provides smooth playback and audio, but some other environments may not support MPV and so will default when possible to the native hydrus software renderer, which does not support audio. When something does not render how you want, right-clicking on its thumbnail presents the option 'open externally', which will open the file in the appropriate default program (e.g. ACDSee, VLC).
+
+The client can also download files from several websites, including 4chan and other imageboards, many boorus, and gallery sites like deviant art and hentai foundry. You will learn more about this later.
+
+## inbox and archiving
+
+The client sends newly imported files to an **inbox**, just like your email. Inbox acts like a tag, matched by 'system:inbox'. A small envelope icon is drawn in the top corner of all inbox files:
+
+![](images/fresh_imports.png)
+
+If you are sure you want to keep a file long-term, you should **archive** it, which will remove it from the inbox. You can archive from your selected thumbnails' right-click menu, or by pressing ++f7++. If you make a mistake, you can spam ++ctrl+z++ for undo or hit ++shift+f7++ on any set of files to explicitly return them to the inbox.
+
+Anything you do not want to keep should be deleted by selecting from the right-click menu or by hitting the delete key. Deleted files are sent to the trash. They will get a little trash icon:
+
+![](images/processed_imports.png)
+
+A trashed file will not appear in subsequent normal searches, although you can search the trash specifically by clicking the 'my files' button on the autocomplete dropdown and changing the file domain to 'trash'. Undeleting a file (++shift+delete++) will return it to 'my files' as if nothing had happened. Files that remain in the trash will be permanently deleted, usually after a few days. You can change the permanent deletion behaviour in the client's options.
+
+A quick way of processing new files is–
+
+## filtering
+
+Lets say you just downloaded a good thread, or perhaps you just imported an old folder of miscellany. You now have a whole bunch of files in your inbox--some good, some awful. You probably want to quickly go through them, saying _yes, yes, yes, no, yes, no, no, yes_, where _yes_ means 'keep and archive' and _no_ means 'delete this trash'. **Filtering** is the solution.
+
+Select some thumbnails, and either choose _filter->archive/delete_ from the right-click menu or hit F12. You will see them in a special version of the media viewer, with the following controls:
+
+*   ++left-button++, ++space++, or ++f7++: **keep and archive the file, move on**
+*   ++right-button++ or ++delete++: **delete the file, move on**
+*   ++up++: **Skip this file, move on**
+*   ++middle-button++ or ++backspace++: **I didn't mean that, go back one**
+*   ++escape++, ++return++, or ++f12++: **stop filtering now**
+
+Your choices will not be committed until you finish filtering.
+
+This saves time.
+
+## lastly
+
+The hydrus client's workflows are not designed for half-finished files that you are still working on. Think of it as a giant archive for everything excellent you have decided to store away. It lets you find and remember these things quickly.
+
+In general, hydrus is good for individual files like you commonly find on imageboards or boorus. Although advanced users can cobble together some page-tag-based solutions, it is not yet great for multi-file media like comics and definitely not as a typical playlist-based music player.
+
+If you are looking for a comic manager to supplement hydrus, check out this user-made guide to other archiving software [here](https://github.com/CuddleBear92/Hydrus-Presets-and-Scripts/wiki/0-Alternative-Programs-and-Resources#software)!
+
+And although the client can hold millions of files, it starts to creak and chug when displaying or otherwise tracking more than about 40,000 or so in a single gui window. As you learn to use it, please try not to let your download queues or general search pages regularly sit at more than 40 or 50k total _items_, or you'll start to slow other things down. Another common mistake is to leave one large 'system:everything' or 'system:inbox' page open with 70k+ files. For these sorts of 'ongoing processing' pages, try adding a 'system:limit=256' to keep them snappy. One user mentioned he had regular gui hangs of thirty seconds or so, and when we looked into it, it turned out his handful of download pages had three million files queued up! Just try and take things slow until you figure out what your computer's limits are.
+
+[I want to learn more about files! ---->](getting_started_more_files.md)
+
+[No, let's learn about tags! ---->](getting_started_tags.md)

docs/getting_started_installing.md

@@ -0,0 +1,143 @@
+---
+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
+
+You can get the latest release at [my 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
+
+!!! 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.
+
+=== "Windows"
+
+    *   If you want the easy solution, download the .exe installer. Run it, hit ok several times.
+    *   If you know what you are doing and want a little more control, get the .zip. Don't extract it to Program Files unless you are willing to run it as administrator every time (it stores all its user data inside its own folder). You probably want something like D:\\hydrus.
+    *   _Note if you run <Win10, you may need [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145), if you don't already have it for vidya. If you run Win7, you will need some/all core OS updates released before 2017._
+    *   If you use Windows 10 N (a version of Windows without some media playback features), you will likely need the 'Media Feature Pack'. There have been several versions of this, so it may best found by searching for the latest version or hitting Windows Update, but otherwise check [here](https://support.microsoft.com/en-us/help/3145500/media-feature-pack-list-for-windows-n-editions).
+
+=== "macOS"
+
+    *   Get the .dmg App. Open it, drag it to Applications, and check the readme inside.
+
+=== "Linux"
+
+    *   Get the .tag.gz. Extract it somewhere useful and create shortcuts to 'client' and 'server' as you like. The build is made on Ubuntu, so if you run something else, compatibility is hit and miss.
+    *   If you use Arch Linux, you can check out the AUR package a user maintains [here](https://aur.archlinux.org/packages/hydrus/).
+    *   If you have problems running the Ubuntu build, users with some python experience generally find running from source works well.
+    *   You might need to get 'libmpv1' to get mpv working and playing video/audio. This is the mpv library, not the player. Check help->about to see if it is available--if not, see if you can get it with _apt_.
+    *   You can also try [running the Windows version in wine](wine.md).
+
+=== "From Source"
+
+    *   If you have some python experience, you can [run from source](running_from_source.md).
+
+By default, hydrus stores all its data—options, files, subscriptions, _everything_—entirely inside its own directory. You can extract it to a usb stick, move it from one place to another, have multiple installs for multiple purposes, wrap it all up inside a truecrypt volume, whatever you like. The .exe installer writes some unavoidable uninstall registry stuff to Windows, but the 'installed' client itself will run fine if you manually move it.
+
+!!! 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.
+
+## running
+
+To run the client:
+
+=== "Windows"
+
+    *   For the installer, run the Start menu shortcut it added.
+    *   For the extract, run 'client.exe' in the base directory, or make a shortcut to it.
+
+=== "macOS"
+
+    *   Run the App you installed.
+
+=== "Linux"
+
+    *   Run the 'client' executable in the base directory. You may be able to double-click it, otherwise you are talking './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
+
+!!! danger
+    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!
+
+**Hydrus does not auto-update. It will stay the same version unless you download and install a new one.**
+
+Although I put out an new version every week, you can update far less often if you want. The client keeps to itself, so if it does exactly what you want and a new version does nothing you care about, you can just leave it. Other users enjoy updating every week, simply because it makes for a nice schedule. Others like to stay a week or two behind what is current, just in case I mess up and cause a temporary bug in something they like.
+
+A user has written a longer and more formal guide to updating, and information on the 334->335 step [here](update_guide.rtf).
+
+The update process:
+
+*   If the client is running, close it!
+*   If you maintain a backup, run it now!
+*   If you use the installer, just download the new installer and run it. It should detect where the last install was and overwrite everything automatically.
+*   If you extract, then just extract the new version right on top of your current install and overwrite manually.
+*   Start your client or server. It may take a few minutes to update its database. I will say in the release post if it is likely to take longer.
+
+Unless the update specifically disables or reconfigures something, all your files and tags and settings will be remembered after the update.
+
+Releases typically need to update your database to their version. New releases can retroactively perform older database updates, so if the new version is v255 but your database is on v250, you generally only need to get the v255 release, and it'll do all the intervening v250->v251, v251->v252, etc... update steps in order as soon as you boot it. If you need to update from a release more than, say, ten versions older than current, see below. You might also like to skim the release posts or [changelog](changelog.html) to see what is new.
+
+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
+
+**This is only relevant if you update and cannot boot at all.**
+
+Very rarely, hydrus needs a clean install. This can be due to a special update like when we moved from 32-bit to 64-bit or needing to otherwise 'reset' a custom install situation. The problem is usually that a library file has been renamed in a new version and hydrus has trouble figuring out whether to use the older one (from a previous version) or the newer.
+
+In any case, if you cannot boot hydrus and it either fails silently or you get a crash log or system-level error popup complaining in a technical way about not being able to load a dll/pyd/so file, you may need a clean install, which essentially means clearing any old files out and reinstalling.
+
+However, you need to be careful not to delete your database! It sounds silly, but at least one user has made a mistake here. The process is simple, do not deviate:
+
+*   Make a backup if you can!
+*   Go to your install directory.
+*   Delete all the files and folders except the 'db' dir (and all of its contents, obviously).
+*   Reinstall/extract hydrus as you normally do.
+
+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
+
+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.
+
+As a result, if you get a failure on trying to do a big update, try cutting the distance in half--try v270 first, and then if that works, try v270->v290. If it doesn't, try v260, and so on.
+
+If you narrow the gap down to just one version and still get an error, please let me know. I am very interested in these sorts of problems and will be happy to help figure out a fix with you (and everyone else who might be affected).
+
+## backing up
+
+**Maintaining a regular backup is important for hydrus.** The program stores a lot of complicated data that you will put hours and hours of work into, and if you only have one copy and your hard drive breaks, you could lose everything. This has happened before, and it sucks to go through. Don't let it be you.
+
+If you do not already have a backup routine for your files, this is a great time to start. I now run a backup every week of all my data so that if my computer blows up or anything else awful happens, I'll at worst have lost a few days' work. Before I did this, I once lost an entire drive with tens of thousands of files, and it felt awful. If you are new to saving a lot of media, I hope you can avoid what I felt. ;\_;
+
+I use [ToDoList](http://abstractspoon.com/) to remind me of my jobs for the day, including backup tasks, and [FreeFileSync](http://sourceforge.net/projects/freefilesync/) to actually mirror over to an external usb drive. I recommend both highly (and for ToDoList, I recommend hiding the complicated columns, stripping it down to a simple interface). It isn't a huge expense to get a couple-TB usb drive either--it is **absolutely** worth it for the peace of mind.
+
+By default, hydrus stores all your user data in one location, so backing up is simple:
+
+*   #### 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.
+    
+    Once you have your location set up, you can thereafter hit _database->update database backup_. It will lock everything and mirror your files, showing its progress in a popup message. The first time you make this backup, it may take a little while (as it will have to fully copy your database and all its files), but after that, it will only have to copy new or altered files and should only ever take a couple of minutes.
+    
+    Advanced users who have migrated their database across multiple locations will not have this option--use an external program in this case.
+    
+*   #### the powerful way - using an external program
+    
+    If you would like to integrate hydrus into a broader backup scheme you already run, or you are an advanced user with a complicated hydrus install that you have migrated across multiple drives, then you need to backup two things: the client\*.db files and your client\_files directory(ies). By default, they are all stored in install\_dir/db. The .db files contain your settings and file metadata like inbox/archive and tags, while the client\_files subdirs store your actual media and its thumbnails. If everything is still under install\_dir/db, then it is usually easiest to just backup the whole install dir, keeping a functional 'portable' copy of your install that you can restore no prob. Make sure you keep the .db files together--they are not interchangeable and mostly useless on their own!
+    
+    Shut the client down while you run the backup, obviously.
+    
+!!! danger
+    Do not put your live database in a folder that continuously syncs to a cloud backup. Many of these services will interfere with a running client and can cause database corruption. If you still want to use a system like this, either turn the sync off while the client is running, or use the above backup workflows to safely backup your client to a separate folder that syncs to the cloud.
+
+I recommend you always backup before you update, just in case there is a problem with my code that breaks your database. If that happens, please [contact me](contact.html), describing the problem, and revert to the functioning older version. I'll get on any problems like that immediately.
+
+[Let's import some files! ---->](getting_started_files.html)

docs/getting_started_ratings.md

@@ -0,0 +1,42 @@
+---
+title: ratings
+---
+# getting started with ratings  
+
+[<\-\-\- Back to downloading](getting_started_downloading.html)
+
+The hydrus client supports two kinds of ratings: _like/dislike_ and _numerical_. Let's start with the simpler one:
+
+## like/dislike
+
+A new client starts with one of these, called 'favourites'. It can set one of two values to a file. It does not have to represent like or dislike--it can be anything you want, like 'send to export folder' or 'explicit/safe' or 'cool babes'. Go to _services->manage services->local->like/dislike ratings_:
+
+![](ratings_like.png)
+
+You can set a variety of colours and shapes.
+
+## numerical
+
+This is '3 out of 5 stars' or '8/10'. You can set the range to whatever whole numbers you like:
+
+![](images/ratings_numerical.png)
+
+As well as the shape and colour options, you can set how many 'stars' to display and whether 0/10 is permitted.
+
+If you change the star range at a later date, any existing ratings will be 'stretched' across the new range. As values are collapsed to the nearest integer, this is best done for scales that are multiples. 2/5 will neatly become 4/10 on a zero-allowed service, for instance, and 0/4 can nicely become 1/5 if you disallow zero ratings in the same step. If you didn't intuitively understand that, just don't touch the number of stars or zero rating checkbox after you have created the numerical rating service!
+
+## now what?
+
+Ratings are displayed in the top-right of the media viewer:
+
+![](images/ratings_ebola_chan.png)
+
+Hovering over each control will pop up its name, in case you forget which is which. You can set then them with a left- or right-click. Like/dislike and numerical have slightly different click behaviour, so have a play with them to get their feel. Pressing F4 on a selection of thumbnails will open a dialog with a very similar layout, which will let you set the same rating to many files simultaneously.
+
+Once you have some ratings set, you can search for them using system:rating, which produces this dialog:
+
+![](images/ratings_system_pred.png)
+
+On my own client, I find it useful to have several like/dislike ratings set up as one-click pseudo-tags, like the 'OP images' above.
+
+[Go back to the index --->](index.html)

docs/getting_started_tags.md

@@ -0,0 +1,100 @@
+---
+title: tags
+---
+
+# getting started with tags
+
+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)!
+
+## how do we find files?
+
+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.html#tags)
+
+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:
+
+[![](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:
+
+*   `character:batman`
+*   `series:street fighter`
+*   `person:jennifer lawrence`
+*   `title:vitruvian man`
+
+The client is set up to draw common namespaces in different colours, just like boorus do. You can change these colours in the options.
+
+Once you are happy with your tags, hit 'apply' or just press enter on the text box if it is empty.
+
+[![](images/sororitas_local_done.png)](images/sororitas_local_done.png)
+
+The tags are now saved to your database. Searching for any of them will return this file and anything else so tagged:
+
+[![](images/sororitas_search.png)](images/sororitas_search.png)
+
+If you add more tags or system predicates to a search, you will limit the results to those files that match every single one:
+
+[![](images/sororitas_hanako.png)](images/sororitas_hanako.png)
+
+You can also exclude a tag by prefixing it with a hyphen (e.g. '-heresy').
+
+## OR searching
+
+Searches find files that match every search 'predicate' in the list (it is an **AND** search), which makes it difficult to search for files that include one **OR** another tag. More recently, simple OR search support was added. All you have to do is hold down Shift when you enter/double-click a tag in the autocomplete entry area. Instead of sending the tag up to the active search list up top, it will instead start an under-construction 'OR chain' in the tag results below:
+
+![](images/or_under_construction.png)
+
+You can keep searching for and entering new tags. Holding down Shift on new tags will extend the OR chain, and entering them as normal will 'cap' the chain and send it to the complete and active search predicates above.
+
+![](images/or_done.png)
+
+Any file that has one or more of those OR sub-tags will match.
+
+If you enter an OR tag incorrectly, you can either cancel or 'rewind' the under-construction search predicate with these new buttons that will appear:
+
+![](images/or_buttons.png)
+
+You can also cancel an under-construction OR by hitting Esc on an empty input. You can add any sort of search term to an OR search predicate, including system predicates. Some unusual sub-predicates (typically a '-tag', or a very broad system predicate) can run very slowly, but they will run much faster if you include non-OR search predicates in the search:
+
+![](images/or_mixed.png)
+
+This search will return all files that have the tag 'fanfic' and one or more of 'medium:text', a positive value for the like/dislike rating 'read later', or PDF mime.
+
+## 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.
+
+Tag repos store many file->tag relationships. Anyone who has an access key to the repository can sync with it and hence download all these relationships. If any of their own files match up, they will get those tags. Access keys will also usually have permission to upload new tags and ask for incorrect ones to be deleted.
+
+Anyone can run a tag repository, but it is a bit complicated for new users. I ran a public tag repository for a long time, and now this large central store is run by users. It has over a billion tags and is free to access and contribute to.
+
+To connect with it, please check [here](access_keys.html). **Please read that page if you want to try out the PTR. It is only appropriate for someone on an SSD!**
+
+If you add it, your client will download updates from the repository over time and, usually when it is idle or shutting down, 'process' them into its database until it is fully synchronised. The processing step is CPU and HDD heavy, and you can customise when it happens in _file->options->maintenance and processing_. As the repository synchronises, you should see some new tags appear, particularly on famous files that lots of people have.
+
+You can watch more detailed synchronisation progress in the _services->review services_ window.
+
+![](images/review_repos_public_tag_repo.png)
+
+Your new service should now be listed on the left of the manage tags dialog. Adding tags to a repository works very similarly to the 'my tags' service except hitting 'apply' will not immediately confirm your changes--it will put them in a queue to be uploaded. These 'pending' tags will be counted with a plus '+' or minus '-' sign:
+
+[![](images/rlm_pending.png)](images/rlm_pending.png)
+
+Notice that a 'pending' menu has appeared on the main window. This lets you start the upload when you are ready and happy with everything that you have queued.
+
+When you upload your pending tags, they will commit and look to you like any other tag. The tag repository will anonymously bundle them into the next update, which everyone else will download in a day or so. They will see your tags just like you saw theirs.
+
+If you attempt to remove a tag that has been uploaded, you may be prompted to give a reason, creating a petition that a janitor for the repository will review.
+
+I recommend you not spam tags to the public tag repo until you get a rough feel for the [guidelines](https://github.com/CuddleBear92/Hydrus-Presets-and-Scripts/blob/master/tag%20guidelines), and my original [tag schema](tagging_schema.html) thoughts, or just lurk until you get the idea. It roughly follows what you will see on a typical booru. The general rule is to only add factual tags--no subjective opinion.
+
+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.html#delays)
+
+[Read about downloading --->](getting_started_downloading.html)
+
+[Go back to the index --->](index.html)