docs: document more detailed usage with manual pages for even better reference (#8)

Author: zimeg

.github/workflows/release.yml

@@ -23,3 +23,10 @@ jobs:
           nix develop -c goreleaser release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Include documentation
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION="${TAG#v}"
+          gh release upload "$TAG" man/git-coverage.1#git-coverage_"$VERSION"_man.1
+        env:
+          GH_TOKEN: ${{ github.token }}

CHANGELOG.md

@@ -10,6 +10,7 @@ to [Semantic Versioning][semver].
 ### Added
 
 - Print usage details to standard output if a help flag is used in command.
+- Document more detailed usage with manual pages for even better reference.
 
 ### Maintenance
 

README.md

@@ -20,4 +20,12 @@ Options are available for customization:
 
 Add a build to `$PATH` for automatic detection.
 
+Read manual pages:
+
+```sh
+$ cp ./man/git-coverage.1 /usr/local/share/man/man1/
+$ mandb
+$ man git-coverage
+```
+
 [codecov]: https://about.codecov.io

flake.nix

@@ -22,9 +22,15 @@
           version = "unversioned";
           src = ./.;
           nativeBuildInputs = [
+            pkgs.installShellFiles
             pkgs.zig.hook
           ];
           zigBuildFlags = [ "-Doptimize=ReleaseSmall" ];
+          installPhase = ''
+            mkdir -p $out/bin
+            cp zig-out/bin/git-coverage $out/bin/
+            installManPage man/git-coverage.1
+          '';
         };
         devShells.default = pkgs.mkShell {
           packages = [

man/git-coverage.1

@@ -0,0 +1,51 @@
+.TH GIT-COVERAGE "1" "2025-05-10" "git-coverage 0.1.0" "Git Manual"
+.
+.SH NAME
+git-coverage \- Open test coverage uploaded to \fBcodecov\fP in a web browser.
+.
+.
+.SH SYNOPSIS
+.B
+git coverage [\fIoptions\fP]
+.
+.
+.SH DESCRIPTION
+The \fBgit-coverage\fP program opens test coverage results uploaded to \fBcodecov\fP using \fIgit-remote\fP(1) details.
+.
+.
+.SH OPTIONS
+.
+.IP "-h, --help"
+Print these usage details.
+.
+.
+.SH EXIT STATUS
+An exit code of \fB0\fP is returned if a link to coverage results on \fBcodecov\fP can be constructed.
+.sp 2
+If the browser cannot be opened a link to coverage results is output to \fBstdout\fP before exiting.
+.sp 2
+Errors in \fIgit\fP(1) configurations or provided flag \fIoptions\fP exits with a non-zero error code.
+.
+.
+.SH STANDARDS
+The latest release of \fBgit\fP is recommended.
+.
+.
+.SH HISTORY
+\fIhttps://github.com/zimeg/git-coverage/releases/\fP
+.
+.
+.SH EXAMPLES
+.
+.IP "$ git coverage"
+Open test coverage results for the current project in a web browser.
+.
+.
+.SH REPORTING BUGS
+\fIhttps://github.com/zimeg/git-coverage/issues/\fP
+.
+.
+.SH SEE ALSO
+\fIgit-remote\fP(1)
+.nf
+\fIhttps://about.codecov.io/\fP