Write a manual page

Decided to finally move documentation out of the README and into a
manual. Also setup building the actual man page with Pandoc and putting
it into the build artifacts.

This is also a version bump to 14 since I felt like it.

.github/workflows/d.yml

@@ -13,6 +13,7 @@ jobs:
 
     steps:
     - uses: actions/checkout@v2
+    - uses: r-lib/actions/setup-pandoc@v1
     - uses: dlang-community/setup-dlang@v1
       with:
         compiler: ldc-latest
@@ -26,6 +27,9 @@ jobs:
         dub build --build=release --compiler=$DC
         strip trash
 
+    - name: Man Page with Pandoc
+      run: "pandoc -s -t man -o trash.man MANUAL.md"
+
     - name: Build Distro Packages
       run: |
         sudo gem install fpm
@@ -35,7 +39,9 @@ jobs:
       uses: actions/upload-artifact@v2
       with:
         name: "trash-d"
-        path: "trash"
+        path: |
+              trash
+              trash.man
   
     - name: Upload Coverage Logs
       uses: actions/upload-artifact@v2

.gitignore

@@ -36,3 +36,5 @@ test-trash/
 
 # Built packages
 pkg/
+*.1
+*.man

MANUAL.md

@@ -0,0 +1,132 @@
+---
+title: TRASH-D
+section: 1
+header: User Manual
+footer: trash-d 14
+date: November 24, 2021
+---
+
+NAME
+====
+
+trash-d - A near drop-in replacement for **rm** that uses the trash bin
+
+SYNOPSIS
+========
+
+trash [_option_]... _file_...
+
+DESCRIPTION
+===========
+
+A near drop-in replacement for **rm**(1) that uses the FreeDesktop trash bin.
+Written in the D programming language using only D's Phobos standard library.
+
+One of **trash-d**'s primary goals is near compatibility with the standard
+**rm** tool.The keyword here is "near". The goal is not exact flag-for-flag
+compatibility with **rm**, but you should be able to **alias rm=trash** and not
+notice the difference.
+
+OPTIONS
+=======
+
+The options and flags are intended to mirror **rm**'s closely, with some
+additional long options for the **trash-d** specific features.
+
+Because of this, **trash-d** will silently ignore unknown options.  Be warned
+that this may be subject to change as **trash-d**'s compatibility with **rm**
+increases.
+
+**-d**, **-\-dir**
+: Remove empty directories.
+
+**-r**, **-\-recursive**
+: Delete directories and their contents.
+
+**-v**, **-\-verbose**
+: Print more information.
+
+**-i**, **-\-interactive**
+: Ask before each deletion.
+
+**-f**, **-\-force**
+: Don't prompt and ignore errors.
+
+**-\-version**
+: Output the version and exit.
+
+**-\-list**
+: List out the files in the trash.
+
+**-\-orphans**
+: List orphaned files in the trash.
+
+**-\-delete** _file_
+: Delete a file from the trash.
+
+**-\-restore** _file_
+: Restore a file from the trash.
+
+**-\-empty**
+: Empty the trash bin.
+
+**-\-rm** _files_...
+: Escape hatch to permanently delete a file.
+
+**-h**, **-\-help**
+: This help information.
+
+
+Precedence
+----------
+
+The **-\-help**, **-\-version**, **-\-list**, **-\-orphans**, **-\-restore**,
+**-\-delete**, and **-\-empty** flags all cause the program to short-circuit and
+perform only that operation and no others. Their precedence is in that order
+exactly, and is intended to cause the least destruction.
+
+Therefore the command **trash -\-empty -\-list** will list the trash bin and NOT empty
+it.
+
+Before version 11 **trash-d** followed a slightly incorrect precedence order.
+
+ENVIRONMENT
+===========
+
+**XDG_DATA_HOME**
+: This variable is used to determine where the default trash directory is for
+  this user as per the FreeDesktop specification.
+
+**TRASH_D_DIR**
+: Override the trash directory to the specified path.
+
+EXIT STATUS
+===========
+
+**trash-d** exits 0 on success, and >0 if an error occurs.
+
+SEE ALSO
+========
+
+**rm**(1), **user-dirs.conf**(5)
+
+STANDARDS
+=========
+
+By mimicing **rm** this utility is partially POSIX compliant however this is
+**NOT** to be relied upon for any purpose.
+
+The **trash-d** utility is compliant with the FreeDesktop trash specification.
+https://specifications.freedesktop.org/trash-spec/trashspec-latest.html
+
+AUTHOR
+======
+
+Steven vanZyl <rushsteve1@rushsteve1.us>
+
+The up-to-date sources can be found at https://github.com/rushsteve1/trash-d
+
+BUGS
+====
+
+https://github.com/rushsteve1/trash-d/issues

README.md

@@ -7,35 +7,24 @@
 ![Lines of code](https://img.shields.io/tokei/lines/github/rushsteve1/trash-d)
 
 A near drop-in replacement for `rm` that uses the
-[Freedesktop trash bin](https://specifications.freedesktop.org/trash-spec/trashspec-latest.html).
+[FreeDesktop trash bin](https://specifications.freedesktop.org/trash-spec/trashspec-latest.html).
 Written in the [D programming language](https://dlang.org/)
 using only D's Phobos standard library.
 
 **ONLY LINUX AND BSD ARE CURRENTLY SUPPORTED!**
 
 Windows won't work at all, and MacOS probably won't either.
-Any POSIX and Freedesktop compliant system should work fine.
+Any POSIX and FreeDesktop compliant system should work fine.
 PRs for expanding support are very welcome!
 
 You can install a pre-built version (`x86_64-linux-gnu`) from the
-[GitHub releases page](https://github.com/rushsteve1/trash-d/releases)
+  * [ ] [GitHub releases page](https://github.com/rushsteve1/trash-d/releases)
 
 I gave a brief informal talk about this project and D at
 [DoomConf 2021](https://doomconf.netlify.app/)
 (recording is a bit messed up and only has half my talk) you can see also
 [the slides here](https://doomconf.netlify.app/rushsteve1/trash-d)
 
-## `rm` compatibility
-
-One of `trash-d`'s primary goals is near compatibility with the standard `rm`
-tool.The keyword here is "near". The goal is not exact flag-for-flag
-compatibility with `rm`, but you should be able to `alias rm=trash` and not
-notice the difference.
-
-Because of this, `trash-d` will silently ignore unknown options.
-Be warned that this may be subject to change as `trash-d`'s compatibility
-with `rm` increases.
-
 ## Building
 
 `trash-d` can be built using any D compiler, but it uses Dub and DMD by default.
@@ -48,7 +37,8 @@ CMake build files can be generated using `dub generate cmake`.
 
 ### Installing
 
-Simply drop the `trash` binary somewhere on your `$PATH` such as `$HOME/.local/bin`.
+Simply drop the `trash` binary somewhere on your `$PATH` such as
+`$HOME/.local/bin` or use the provided DEB and RPM packages.
 
 Optionally set `alias rm=trash` in your shell config to replace usages of `rm`
 with `trash-d`.
@@ -58,40 +48,19 @@ with `trash-d`.
 Using `trash-d` is the same as most other command line utilities, and
 intentionally very similar to `rm`.
 
-`trash [OPTIONS...] [FILES...]`
-
-### Options & Flags
+See the [manual for more information](./MANUAL.md).
 
-The options and flags are intended to mirror `rm`'s closely, with some
-additional long options for the `trash-d` specific features.
 
-- `-d`, `--dir` Remove empty directories.
-- `-r`, `--recursive` Delete directories and their contents.
-- `-v`, `--verbose` Print more information.
-- `-i`, `--interactive` Ask before each deletion.
-- `-f`, `--force` Don't prompt and ignore errors.
-- `--version` Output the version and exit.
-- `--list` List out the files in the trash.
-- `--orphans` List orphaned files in the trash.
-- `--delete FILE` Delete a file from the trash.
-- `--restore FILE` Restore a file from the trash.
-- `--empty` Empty the trash bin.
-- `--rm` Escape hatch to permanently delete a file.
-- `-h`, `--help` This help information.
+### `rm` compatibility
 
+One of `trash-d`'s primary goals is near compatibility with the standard `rm`
+tool.The keyword here is "near". The goal is not exact flag-for-flag
+compatibility with `rm`, but you should be able to `alias rm=trash` and not
+notice the difference.
 
-#### Option Precedence
-
-The `--help`, `--version`, `--list`, `--orphans`, `--restore`, `--delete`, and
-`--empty` flags all cause the program to short-circuit and perform only that
-operation and no others. Their precedence is in that order exactly, and is
-intended to cause the least destruction.
-
-Therefore the command `trash --empty --list` will list the trash bin and NOT
-empty it.
-
-**NOTE:** Before version 11 `trash-d` followed a slightly incorrect precedence
-order.
+Because of this, `trash-d` will silently ignore unknown options.
+Be warned that this may be subject to change as `trash-d`'s compatibility
+with `rm` increases.
 
 ## Contributing
 

dub.json

@@ -2,7 +2,7 @@
     "authors": ["Steven vanZyl <rushsteve1@rushsteve1.us>"],
     "copyright": "Copyright © 2021, Steven vanZyl",
     "description": "A near drop-in replacement for rm that uses the trash bin",
-    "version": "13",
+    "version": "14",
     "license": "MIT",
     "name": "trash-d",
     "homepage": "https://github.com/rushsteve1/trash-d",

package.rb

@@ -29,7 +29,8 @@
     --description '#{data["description"]}' \
     --url '#{data["homepage"]}' \
     --maintainer '#{data["authors"][0]}' \
-    trash=/usr/bin/trash
+    trash=/usr/bin/trash \
+    trash.man=/usr/share/man/man1/trash.1
   sh
 
   exit(1) if not system(cmd)

source/ver.d

@@ -5,7 +5,7 @@
 import std.format : format;
 
 /// trash-d is versioned sequentially starting at 1
-const int VER = 13;
+const int VER = 14;
 
 /// Ever major release is given a new name
 /// Names are based on video game bosses