Update download-filters.md

docs/download-filters.md

@@ -1,36 +1,71 @@
-# How to use the filters
+# Controlling **downloader** with filters
+
+By default **downloader** will download everything that's available, based on your selections in the configuration menu.  For more specific control over what is being downloaded, the filter option allows you to specify which cores you retrieve or update. For example, you could download only console and arcade cores, but none of the computer cores.
+
+# Filter Use & Syntax
+
+## Where to Add the Filters
 
-In a nutshell:
 1. Edit the file at `/media/fat/downloader.ini`
-2. Add a **filter** property under the `[mister]` section (if it doesn't exist, just create it).
-3. Then, on the right side of the property, you will add the filter terms themselves.
+1. Add a line that starts with `filter =` under the `[mister]` section (if it doesn't exist, just create it).
+1. Then, after `filter =`, add the filter terms themselves.
+
+  - A list of official MiSTer filter terms [is available here](https://github.com/MiSTer-devel/Distribution_MiSTer)
+  - You can also find terms for [Jotego Cores](https://github.com/jotego/jtcores_mister).
+
+### Example
+
+```
+[mister]
+filter = snes !genesis
+```
+
+  -  The above filter will download the Super NES core, but not the Genesis core.
+  -  Anything listed after `filter =` will be downloaded, unless it's prefixed with an exclamation mark ❗ (which means NOT).
+  -  Note that the symbols `-` and `_` are ignored by the filter, so terms like `pc_engine-cd` and `pcenginecd` are the same.
+  -  Filter terms cannot have spaces in them.  `!pokemon mini` will be interpreted as *no* to pokemon, *yes* to mini.
+
+## Positive and Negative Filters
+**downloader** downloads everything by default.  Depending on your needs, it might make sense to simply filter out everything you don't want, or include everything you *do* want.
+
+  -  ❗ If your filter has only negative terms, **downloader** will download everything *except your negative filters*.
+  -  ‼️ If you include ***any positive terms*** then **downloader** will only download things you explicity include.
+
+### Examples
+
+  -  `filter = console !computer`  will only download console cores.  Even though !computer is explicity excluded, the positive `console` term is the *only* positive, and so it's the only inclusion.
+  -  `filter = arcade !arcade-astrocade` will download only the arcade cores, except the astrocade core.
+  -  `filter = arcade console` will download every arcade and console core, but nothing else.
+  -  `filter= !computer` will download every core except computer cores.
+
+👉 The `essential` cores will always be included unless you specifically remove them with `!essential`.  The `essential` cores include the MiSTer menus, etc, and should not be excluded for most purposes.  
 
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/852246/149841563-78338772-d4ec-4321-8772-6bf79eb840b3.png" /> 
-</p>
-<p align="center"><i>This filter will only install four systems: NES, SNES, GB and GBA.</i></p>
+#  Core Specificity
+Several of the tags you can exlude are groups: `computer`, `console`, `arcade` etc.   Depending on your requirements it's possible to exclude certain cores within those groups.  You can, for example, disable all console cores `!console` but still download  `SNES NES` cores like so:  `filter = !console snes nes`.
 
-As a filter term, you may put a list of space-separated names such as: core names, core categories, file types, etc. Specifically, [these are all the available terms](https://github.com/MiSTer-devel/Distribution_MiSTer#tags-that-you-may-use-with-download-filters-feature) that you may use right now.
+  - `filter = !cheats !other !arcade-bankpanic` will download everything *except* `cheats`, `other` (which includes standalone systems like Game n Watch) and the bankpanic arcade core.
+  - `filter = arcade !arcade-asteroids !arcade-cave` will only download arcade cores, except the asteroids and Cave cores.
 
-Is also worth mentioning that symbols `-` and `_` within the term are ignored by the system. So in the eyes of Downloader, the terms `pc_engine-cd` and `pcenginecd` would be equivalent.
+### 👉 Many cores are responsible for more than one game.
 
-For negative filter terms, you would have to prepend an exclamation mark `!` before the term. In the following example, the filter is saying *"I want all the arcade, console and computer cores, except the Pong Arcade"*:
+The `Astrocade` core covers games like _Wizard of Wor_ and _Gorf_, and the `Cave` core covers _DonPachi_, _Dangun Feveron_, and so on.  You can usually find a list of every game handled by one core by searching for it.  Google `mister astrocade core` and the first result, usually on github, will almost always include a list of the games it runs.  For things like `console` cores this obviously isn't necessary - if you disable the Super NES core, you simply won't get Super NES.
 
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/852246/149841891-86f35c2f-10a2-4ed1-a08f-374f68dd921b.png" />
-</p>
-<p align="center"><i>The term 'arcade-pong' is negated, thus Pong files will be substracted from all previously matched files.</i></p>
+If you disable a core that you have downloaded previously with **downloader** it will be deleted, along with all the associated files (MRAs, cores etc) but it won't remove your configuration settings.
 
-You may also have a filter that only contains negative terms. In that case, the filter will get everything except the files matching these terms. In the next example, we take advantage of this to only remove *Cheats* and *Documentation* files, while keeping everything else:
+# Database-scoped filters
+If you add a filter under `[mister]` it will be global, so the filter will affect **all** databases.  If you put it under a different heading, for example `[distribution_mister]`, it will affect only to that database.  In the case of a duplicate filter entry, filters under database-scoped filters will override filters in the global filter (`[mister]`).
 
-https://www.youtube.com/watch?v=jBxls-yGtvI
+## Combining Filters 
+If you want to include the global filter in another section, you can use `filter = [mister]` to include all terms under `[mister]`.  
 
-### Database-scoped filters: Using the filter property in another section, other than [mister]
-If you add a **filter** property under `[mister]` it will be global, so the filter will affect all databases. But you can constraint the filter so it only applies to a single database. For example, if you add the filter under the section `[distribution_mister]`, it will affect only to the **distribution_mister** database. And if both are defined at the same time, the database-scoped filters will always override whatever it is in the global filter (again, the one under `[mister]`).
+For example, if the global filter under `[mister]` is `filter = console computer` and the `[distribution_mister]` filter is , the database-specific filter will inherit terms from the global filter and add the arcade term. The resulting filter will be `filter = console computer arcade`.
 
-If you want to use the global filter terms and add database-specific terms, include the special term `[mister]` in the database-specific filter. For example, if the global filter under `[mister]` is `filter = console computer` and the `[distribution_mister]` filter is `filter = [mister] arcade`, the database-specific filter will inherit terms from the global filter and add the arcade term. The resulting filter will be `filter = console computer arcade`.
+```
+[distribution_mister]
+filter = [mister] arcade
+```
 
-### Porting filters from the old Updater
+# Porting filters from the old Updater
 
 Most of the terms from [this list](https://github.com/MiSTer-devel/Distribution_MiSTer#tags-that-you-may-use-with-download-filters-feature), are the same terms that you could use in the filters from the old updater. That means, for the most part, filters are compatible with the old updater format. Thus, the transition is very straightforward, as you can see in this video: