Merge pull request 'Better README' (#15) from readme into main

Reviewed-on: #15

README.md

@@ -68,17 +68,14 @@ Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.c
 - A `man(1)` entry
 
 ### Low Priority:
-- `fish(1)` autocomplete
+- Shell autocomplete
-- `bash(1)` autocomplete
-- `zsh(1)` autocomplete
-- [Nushell](https://www.nushell.sh/) autocomplete
 - Configurable search result display like [Starship](https://starship.rs)
-- Versioning system repository package management & compilation
+- Version-control system repository package management & compilation
 
-## External-Dependent:
+### External-Dependent:
 - Conflict resolution
 - Dependency resolution
-- Integration into [PolyMC](https://polymc.org/) and/or
+- Integration into [Prism Launcher](https://prismlauncher.org/) and/or
 [theseus](https://github.com/modrinth/theseus)
 - Integration into `topgrade(1)`
 - Graphical frontend with notifications
@@ -86,142 +83,195 @@ Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.c
 [Modrinth REST API
 docs](https://docs.modrinth.com/api-spec/)
 
-# File Architecture
+# File Structure
 
 ```
-~/.hopper/
+├── "$XDG_CONFIG_HOME"/hopper.toml
-├── hopper.conf
+├── "$XDG_CACHE_HOME"/hopper/
-├── cache/
 │   ├── 1.19.1/
 │   │ └── fabric/
 │   └── 1.18.2/
 │     ├── forge/
 │     └── plugin/
-└── templates/
+└── "XDG_DATA_HOME"/templates/
       └── example-template.hop -> ~/.minecraft/mods/example-template.hop
 ```
 
 # Hopfile Structure
 
-Hopfiles will contain a Minecraft version number, a list of packages, the name
+Hopfiles will contain a Minecraft version number, a list of packages, and any 
-of the type of package it uses, and any references to other hopfiles it's based
+references to other hopfiles on which it's based, or "templates". If a hopfile
-on, or "templates". If a hopfile is based on other template hopfiles, it
+is based on other template hopfiles, it inherits the packages from them. A
-inherits the packages from them. A hopfile does not inherit the package or
+hopfile does not inherit the package or Minecraft version from a template.
-Minecraft version from a template.
 
 ```
-template = example-template
+template = "example-template"
-
+mc-version = "1.19.2"
-mc-version = 1.19.2
-
-type = fabric
 
 [packages]
-sodium
+fabric-mod = [ "sodium", "lithium" ]
+resource = "alacrity"
 ```
 
 # Hopper Configuration File Structure
 
 Hopper's configuration will be maintained with a list of all hopfiles known to
-hopper. Its config will also contain a list of mod hosting sites like Modrinth
+hopper. Its config file will also contain a list of mod hosting sites like
-and CurseForge and a list of (remote or local) version-control repositories from
+Modrinth and CurseForge and a list of (remote or local) version-control
-which to compile mods. The latter will use a (potentially custom) build file
+repositories from which to compile mods. The latter will use a (potentially
-format to be defined at a later date.
+custom) build file format to be defined at a later date.
 
 ```
-[hopfiles]
+hopfiles = [
-file = ~/.minecraft/mods/1.19.1.hop
+  "~/.minecraft/mods/template.hop",
+  "~/.minecraft/1.91.1/mods/1.19.1.hop" 
+]
 
-# Mod Hosts
+[sources]
-
+modrinth = "https://api.modrinth.com/"
-[Modrinth]
+curseforge = "https://api.curseforge.com/"
-api = https://api.modrinth.com/
+git = [
-
+  "git+https://github.com/IrisShaders/Iris.git"
-[CurseForge]
+  "git+https://github.com/CaffeineMC/sodium-fabric.git"
-api = https://api.curseforge.com/
+]
-
-# Git Repositories
-
-[Iris Shaders]
-source = git+https://github.com/IrisShaders/Iris.git
 ```
 
 # Docs
 
+## Types
+
+There are multiple types of packages hopper can manage.
+
+### Mods
+- `fabric-mod`
+- `forge-mod`
+- `quilt-mod`
+
+### Plugins
+- `bukkit-plugin`
+- `paper-plugin`
+- `purpur-plugin`
+- `spigot-plugin`
+- `sponge-plugin`
+
+### Other
+- `data-pack`
+- `fabric-pack`
+- `forge-pack`
+- `resource-pack`
+- `quilt-pack`
+
+These types are specified in various hopper subcommands and in its configuration.
+
 ## Usage
 
-`hopper [SUBCOMMAND] [OPTIONS]`
+`hopper [options...] [subcommand...]`
-
-## Common OPTIONS:
-
-`-d`, `--dir [FILE]`
-
- Specifies the path for the hopfile being utilized
-
-`-f`, `--filename [FILE]`
-
- Saves to a specific file name.
-
-`-m`, `--mc-version [VERSION]`
-
- Specifies for what VERSION of Minecraft PACKAGES are being managed
-
-`-t`, `--type [TYPE]`
-
- Specifies what TYPE of PACKAGEs is being referenced. TYPEs include
-modloader names like `fabric`, `forge`, and `quilt`, as well as `resource` packs
-and mod`pack`s.
 
+## OPTIONS
 
 `-v`, `--verbose`
 
- Includes debug information in the output of `hopper` commands.
+ Includes debug information in the output of `hopper` subcommands.
 
-## SUBCOMMANDs
+## SUBCOMMANDS
 
-`get [OPTIONS] PACKAGE`
+`get [options...] [targets...]`
 
- Searches for a PACKAGE, displays the results, and downloads any selected
+ Searches for packages, displays the results, and downloads any selected
-PACKAGES to the local cache.
+packages to the local cache. If multiple targets are specified, results are
+displayed in order of specification.
 
 OPTIONS
 
+ `-d`, `--dir [directory...]`
+
+  Specifies the directory to download to (default is
+"$XDG_CACHE_HOME"/hopper/).
+
+ `-m`, `--mc-version [version...]`
+
+  Specifies for what version of Minecraft packages are being
+retrieved.
+
  `-n`, `--no-confirm`
 
   Does not display search results and downloads exact matches to the
 cache. Requires `--mc-version` and `--type` be specified.
 
-`init [OPTIONS] --mc-version VERSION --type TYPE TEMPLATE`
+ `-t`, `--type [types...]`
+
+  Specifies what types of packages are being queried.
+
+`init [options...]`
 
  Creates a hopfile in the current directory and adds it to the global known
-hopfiles list in the configuration file. If a TEMPLATE is passed as an
+hopfiles list.
-argument, the hopfile is added as a new template. A name is generated
-using the VERSION and TYPE specified unless `--filename` is used.
 
 OPTIONS
 
- `--template [TEMPLATE1,TEMPLATE2...]`
+ `-d`, `--dir [directory...]`
 
-  Specifies TEMPLATE hopfiles' names upon which to base the new
+  Specifies the directory in which the hopfile is being created.
-hopfile.
 
-`install [OPTIONS] PACKAGE`
+ `-f`, `--hopfile [hopfiles...]`
 
- Adds a PACKAGE to the current hopfile and runs `hopper update`. If the
+  Specifies templates upon which to base the new hopfile.
-PACKAGE cannot be found in the package cache, it runs `hopper get` first.
+
+ `-m`, `--mc-version [version]`
+
+  Specifies for what version of Minecraft packages are being managed.
+
+ `-t`, `--type [type...]`
+
+  Specifies what type of packages will be listed in this hopfile.
+
+`install [options...] [packages...]`
+
+ Adds packages to the current hopfile, symlinking them to its directory. If
+the package cannot be found in the package cache, `hopper get` is run first.
 
 OPTIONS
 
- `--template [TEMPLATE1,TEMPLATE2...]`
+  `-f`, `--hopfile [hopfiles...]`
 
-  Specifies a template hopfile to which to install mods
+  Specifies hopfiles to which mods will be added.
 
-`list [OPTIONS]`
+`list [options...]`
 
  Lists all installed packages.
 
-`update [OPTIONS] PACKAGE`
+OPTIONS
 
- Updates installed PACKAGEs and adds mods if they're missing to directories
+  `-f` `--hopfile [hopfiles...]`
-with known hopfiles. If a PACKAGE is passed, `--type` must be specified so that
+
-hopper `update`s the correct package.
+  Lists packages installed in a specified hopfile.
+
+ `-m`, `--mc-version [version]`
+
+  Specifies for what version of Minecraft packages are being managed.
+
+ `-t`, `--type [types...]`
+
+  List all packages of a specified type.
+
+`update [options...]`
+
+ Updates installed packages and adds mods if they're missing to directories
+with known hopfiles.
+
+OPTIONS
+
+ `-f`, `--hopfile [hopfiles...]`
+
+  Updates only packages in the specified hopfile. Note that this
+option creates a new file and symlink as it does not update the packages for
+other hopfiles.
+
+ `-m`, `--mc-version [version]`
+
+  Specifies for what version of Minecraft packages are being updated.
+
+ `-t`, `--type [types...] [packages...]`
+
+  Updates only packages of a specified type. Optionally takes a list
+of packages as an argument.