Updating the documentation (#9)

intro.md

@@ -1,3 +1,5 @@
 # Topgrade
 
 Keeping your system up to date usually involves invoking multiple package managers. This results in big, non-portable shell one-liners saved in your shell. To remedy this, **Topgrade** detects which tools you use and runs the appropriate commands to update them.
+
+[Please also refer to the README on GitHub.](https://github.com/topgrade-rs/topgrade/blob/main/README.md)

src/SUMMARY.md

@@ -3,8 +3,8 @@
 - [Get Started](./intro.md)
 - [Upgrading Topgrade](./upgrade.md)
 - [Supported Platforms](./platforms.md)
-- [Windows](./windows/README.md)
-  - [Step]()
-- [Linux]()
-  - [Step]()
+  - [BSD](./bsd/README.md)
+  - [Linux](./linux/README.md)
+  - [MacOs](./macos/README.md)
+  - [Windows](./windows/README.md)
 - [Notifications](./notifications.md)

src/bsd/README.md

@@ -0,0 +1,30 @@
+# DragonFly and Free BSD
+
+## Instalation
+
+Either use `cargo install` or the compiled binaries from the release page.
+The compiled binaries contain a self-upgrading feature.
+
+> Currently, Topgrade requires Rust 1.65 or above. In general, Topgrade tracks
+> the latest stable toolchain.
+
+## Usage
+
+Just run `topgrade`.
+
+## Configuration
+
+See `config.example.toml` for an example configuration file.
+
+### Configuration Path
+
+`${XDG_CONFIG_HOME:-~/.config}`
+
+`topgrade` will look for the configuration file in the following places, in order of priority:
+
+1. `CONFIG_DIR/topgrade.toml`
+2. `CONFIG_DIR/topgrade/topgrade.toml`
+
+If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.
+
+On the first run(no configuration file exists), `topgrade` will create a configuration file at `CONFIG_DIR/topgrade.toml` for you.

src/linux/README.md

@@ -0,0 +1,32 @@
+# GNU/Linux
+
+## Installation
+
+- Arch Linux: [AUR](https://aur.archlinux.org/packages/topgrade)
+- NixOS: [Nixpkgs](https://search.nixos.org/packages?show=topgrade)
+- Void Linux: [XBPS](https://voidlinux.org/packages/?arch=x86_64&q=topgrade)
+
+Other systems users can either use `cargo install` or the compiled binaries from the release page.
+The compiled binaries contain a self-upgrading feature.
+
+> Currently, Topgrade requires Rust 1.65 or above. In general, Topgrade tracks
+> the latest stable toolchain.
+
+## Usage
+
+Just run `topgrade`.
+
+## Configuration
+
+See `config.example.toml` for an example configuration file.
+
+### Configuration Path
+
+`${XDG_CONFIG_HOME:-~/.config}`
+
+1. `CONFIG_DIR/topgrade.toml`
+2. `CONFIG_DIR/topgrade/topgrade.toml`
+
+If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.
+
+On the first run(no configuration file exists), `topgrade` will create a configuration file at `CONFIG_DIR/topgrade.toml` for you.

src/macos/README.md

@@ -0,0 +1,26 @@
+# macOS
+
+## Installation
+
+[Homebrew](https://formulae.brew.sh/formula/topgrade) or [MacPorts](https://ports.macports.org/port/topgrade/)
+
+## Usage
+
+Just run `topgrade`.
+
+## Configuration
+
+See `config.example.toml` for an example configuration file.
+
+### Configuration Path
+
+`${XDG_CONFIG_HOME:-~/.config}`
+
+`topgrade` will look for the configuration file in the following places, in order of priority:
+
+1. `CONFIG_DIR/topgrade.toml`
+2. `CONFIG_DIR/topgrade/topgrade.toml`
+
+If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.
+
+On the first run(no configuration file exists), `topgrade` will create a configuration file at `CONFIG_DIR/topgrade.toml` for you.

src/platforms.md

@@ -1,4 +1,4 @@
-# Supported platforms 
+# Supported platforms
 
 Topgrade should probably work on whichever platform it can be build. The real question is whether Topgrade knows that platform and can utilize its unique features, such as the operating system's package manager. Topgrade is tested on and knows the following platforms:
 
@@ -15,4 +15,3 @@ Topgrade should probably work on whichever platform it can be build. The real qu
 - FreeBSD
 - macOS
 - Windows
-

src/upgrade.md

@@ -1,7 +1,5 @@
 # Upgrading topgrade
 
-The precompiled binaries supplied in the Github releases page are compiled with a self upgrade feature. Topgrade will try to upgrade itself before attempting anything else and will respawn itself when an update is downloaded. If you choose to install Topgrade in this method it is recommended that you place the binary in some place which is writable by your user account, such as `~/.local/bin`.
+The precompiled binaries supplied in the Github releases page are compiled with a self upgrade feature. Topgrade will try to upgrade itself before attempting anything else and will respawn itself when an update is downloaded. If you choose to install Topgrade in this method it is recommended that you place the binary in some place which is writable by your user account, such as `~/.local/bin` or `%APPDATA%`.
 
-If you prefer to have Topgrade installed in system-wide manner then it's recommended to either install it using the OS package manager or `cargo install`. Topgrade will not have the self upgrade feature but it will keep itself up to date by calling the operating system's package manager.
-
-Due to a limitation in deleting used files in Windows, you must place the Topgrade executable in the same drive as your `%TEMP%` directory.
+If you prefer to have Topgrade installed in system-wide manner then it's recommended to using OS package manager or `cargo install`.

src/windows/README.md

@@ -1,6 +1,30 @@
 # Windows
 
-Windows is fully supported by Topgrade. You may elect to install it from Scoop or use the binary in the release page.
+[Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/topgrade.json)
+
+## Usage
+
+Just run `topgrade`.
+
+## Configuration
+
+See `config.example.toml` for an example configuration file.
+
+### Configuration Path
+
+`%APPDATA%`
+
+`topgrade` will look for the configuration file in the following places, in order of priority:
+
+1. `CONFIG_DIR/topgrade.toml`
+2. `CONFIG_DIR/topgrade/topgrade.toml`
+
+If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.
+
+On the first run(no configuration file exists), `topgrade` will create a configuration file at `CONFIG_DIR/topgrade.toml` for you.
+
+## FAQ
+
 It is important to note that Topgrade may be unable to upgrade certain applications used for launching it, including third-party terminals like cmder.
 
 We suggest either creating a shortcut for 'topgrade--keep' or running Topgrade via your preferred shell.