Add linting for manpages

Cargo.toml

@@ -37,24 +37,7 @@ clap_generate = "=3.0.0-beta.4"
 
 [features]
 default = []
-# Adds tests for code generated by `zoxide init`.
+nix_tests = []
-# This requires the following external programs available in $PATH:
-# - bash
-# - black: <https://github.com/psf/black>
-# - dash
-# - elvish: <https://github.com/elves/elvish>
-# - fish: <https://github.com/fish-shell/fish-shell>
-# - mypy: <https://github.com/python/mypy>
-# - nushell: <https://github.com/nushell/nushell>
-# - powershell: <https://github.com/PowerShell/PowerShell>
-# - pylint: <https://github.com/PyCQA/pylint>
-# - shellcheck: <https://github.com/koalaman/shellcheck>
-# - shfmt: <https://github.com/mvdan/sh>
-# - xonsh: <https://github.com/xonsh/xonsh>
-# - zsh: <https://github.com/zsh-users/zsh>
-# Since most users are unlikely to have installed all of the above, these tests
-# are disabled by default.
-shell_tests = []
 
 [profile.release]
 codegen-units = 1

man/zoxide-add.1

@@ -1,13 +1,13 @@
-.TH "zoxide-add" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide-add - add a new directory or increment its rank
+\fBzoxide-add\fR - add a new directory or increment its rank
 .SH SYNOPSIS
-.B zoxide add \fI[PATHS]\fR
+.B zoxide add [PATHS]
 .SH DESCRIPTION
 If the directory is not already in the database, this command creates a new
-entry for it with a default score of \fI1\fR, otherwise, it increments the
+entry for it with a default score of 1, otherwise, it increments the existing
-existing score by \fI1\fR. It then sets the last updated field of the entry to the
+score by 1. It then sets the last updated field of the entry to the current
-current time. After this, it runs the \fBAGING\fR algorithm on the database. See
+time. After this, it runs the \fBAGING\fR algorithm on the database. See
 \fBzoxide\fR(1) for more about the algorithm.
 .sp
 If you'd like to prevent a directory from being added to the database, see the
@@ -19,6 +19,6 @@ Print help information.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

man/zoxide-import.1

@@ -1,20 +1,20 @@
-.TH "zoxide-import" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide-import - import data from other tools
+\fBzoxide-import\fR - import data from other tools
 .SH SYNOPSIS
-.B zoxide import \fIPATH --from FORMAT [OPTIONS]\fR
+.B zoxide import PATH --from FORMAT [OPTIONS]
 .SH OPTIONS
 .TP
-.B --from \fIFORMAT\fR
+.B --from FORMAT
 The format of the database being imported:
 .TS
 tab(|);
 l l.
-    \fIautojump\fR
+    \fBautojump\fR
-    \fIz\fR|For \fIz\fR, \fIz.lua\fR, or \fIzsh-z\fR.
+    \fBz\fR|(for \fBz\fR, \fBz.lua\fR, or \fBzsh-z\fR)
 .TE
 .sp
-\fBNOTE\fR: zoxide only imports paths from autojump, since its matching
+Note: zoxide only imports paths from autojump, since its matching
 algorithm is too different to import the scores.
 .TP
 .B -h, --help
@@ -26,6 +26,6 @@ option merges imported data into the existing database.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

man/zoxide-init.1

@@ -1,28 +1,29 @@
-.TH "zoxide-init" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide-init - generate shell configuration for zoxide
+\fBzoxide-init\fR - generate shell configuration for zoxide
 .SH SYNOPSIS
-.B zoxide init \fISHELL [OPTIONS]\fR
+.B zoxide init SHELL [OPTIONS]
 .SH DESCRIPTION
 To initialize zoxide on your shell:
 .TP
 .B bash
-Add this to your configuration (usually \fI~/.bashrc\fR):
+Add this to your configuration (usually \fB~/.bashrc\fR):
 .sp
 .nf
     \fBeval "$(zoxide init bash)"\fR
 .fi
 .TP
 .B elvish
-Add this to your configuration (usually \fI~/.elvish/rc.elv\fR):
+Add this to your configuration (usually \fB~/.elvish/rc.elv\fR):
 .sp
 .nf
     \fBeval $(zoxide init elvish | slurp)\fR
 .fi
+.sp
 Note: zoxide only supports elvish v0.16.0 and above.
 .TP
 .B fish
-Add this to your configuration (usually \fI~/.config/fish/config.fish\fR):
+Add this to your configuration (usually \fB~/.config/fish/config.fish\fR):
 .sp
 .nf
     \fBzoxide init fish | source\fR
@@ -50,14 +51,14 @@ PowerShell):
 .fi
 .TP
 .B xonsh
-Add this to your configuration (usually \fI~/.xonshrc\fR):
+Add this to your configuration (usually \fB~/.xonshrc\fR):
 .sp
 .nf
     \fBexecx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')\fR
 .fi
 .TP
 .B zsh
-Add this to your configuration (usually \fI~/.zshrc\fR):
+Add this to your configuration (usually \fB~/.zshrc\fR):
 .sp
 .nf
     \fBeval "$(zoxide init zsh)"\fR
@@ -80,14 +81,14 @@ e.g. --cmd j would change the aliases to j and ji respectively.
 .B -h, --help
 Print help information.
 .TP
-.B --hook \fIHOOK\fR
+.B --hook HOOK
 Changes how often zoxide increments a directory's score:
 .TS
 tab(|);
 l l.
-    \fInone\fR|Never
+    \fBnone\fR|Never
-    \fIprompt\fR|At every shell prompt
+    \fBprompt\fR|At every shell prompt
-    \fIpwd\fR|Whenever the directory is changed
+    \fBpwd\fR|Whenever the directory is changed
 .TE
 .TP
 .B --no-aliases
@@ -97,6 +98,6 @@ choose to redefine them.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

man/zoxide-query.1

@@ -1,8 +1,8 @@
-.TH "zoxide-query" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide-query - search for a directory in the database
+\fBzoxide-query\fR - search for a directory in the database
 .SH SYNOPSIS
-.B zoxide query \fI[KEYWORDS] [OPTIONS]\fR
+.B zoxide query [KEYWORDS] [OPTIONS]
 .SH DESCRIPTION
 Query the database for paths matching the keywords. The exact \fBMATCHING\fR
 algorithm is described in \fBzoxide\fR(1).
@@ -11,7 +11,7 @@ algorithm is described in \fBzoxide\fR(1).
 .B --all
 Show deleted directories.
 .TP
-.B --exclude \fIPATH\fR
+.B --exclude PATH
 Exclude a path from query results.
 .TP
 .B -h, --help
@@ -28,6 +28,6 @@ Print the calculated score as well as the matched path.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

man/zoxide-remove.1

@@ -1,8 +1,8 @@
-.TH "zoxide-remove" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide-remove - remove a directory from the database
+\fBzoxide-remove\fR - remove a directory from the database
 .SH SYNOPSIS
-.B zoxide remove \fI[PATHS] [OPTIONS]\fR
+.B zoxide remove [PATHS] [OPTIONS]
 .SH DESCRIPTION
 If you'd like to permanently exclude a directory from the database, see the
 \fB_ZO_EXCLUDE_DIRS\fR environment variable in \fBzoxide\fR(1).
@@ -11,11 +11,11 @@ If you'd like to permanently exclude a directory from the database, see the
 .B -h, --help
 Print help information.
 .TP
-.B -i, --interactive \fI[KEYWORDS]\fR
+.B -i, --interactive [KEYWORDS]
 Use interactive selection. This option requires fzf.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

man/zoxide.1

@@ -1,23 +1,23 @@
-.TH "zoxide" "1" "2021-04-12" "zoxide" "zoxide"
+.TH "ZOXIDE" "1" "2021-04-12" "" "zoxide"
 .SH NAME
-zoxide - a smarter cd command
+\fBzoxide\fR - a smarter cd command
 .SH SYNOPSIS
-.B zoxide \fISUBCOMMAND [OPTIONS]\fR
+.B zoxide SUBCOMMAND [OPTIONS]
 .SH DESCRIPTION
-zoxide is a smarter replacement for your cd command. It keeps track of the
+zoxide is a smarter cd command for your terminal. It keeps track of the
 directories you use most frequently, and uses a ranking algorithm to navigate
 to the best match.
 .SH USAGE
 .nf
-    \fBz\fR \fIfoo\fR        # cd into highest ranked directory matching foo
+$ z foo        # cd into highest ranked directory matching foo
-    \fBz\fR \fIfoo bar\fR    # cd into highest ranked directory matching foo and bar
+$ z foo bar    # cd into highest ranked directory matching foo and bar
 .sp
-    \fBz\fR \fI~/foo\fR      # z also works like a regular cd command
+$ z ~/foo      # z also works like a regular cd command
-    \fBz\fR \fIfoo/\fR       # cd into relative path
+$ z foo/       # cd into relative path
-    \fBz\fR \fI..\fR         # cd one level up
+$ z ..         # cd one level up
-    \fBz\fR \fI-\fR          # cd into previous directory
+$ z -          # cd into previous directory
 .sp
-    \fBzi\fR \fIfoo\fR       # cd with interactive selection (using fzf)
+$ zi foo       # cd with interactive selection (using fzf)
 .fi
 .SH SUBCOMMANDS
 .TP
@@ -43,35 +43,30 @@ Print help information.
 .B -V, --version
 Print version information.
 .SH ENVIRONMENT VARIABLES
-Environment variables must be set before calling \fBzoxide init\fR.
+Environment variables must be set before calling \fBzoxide-init\fR(1).
 .TP
 .B _ZO_DATA_DIR
-Specifies the directory in which zoxide should store its database. The default
+Specifies the directory in which the database is stored. The default value
-value varies across OSes:
+varies across OSes:
 .TS
 tab(|);
 l l.
     \fBOS|Path\fR
-    Linux/BSD|T{
+    \fBLinux/BSD\fR|T{
-\fI$XDG_DATA_HOME\fR or \fI$HOME/.local/share\fR
+\fB$XDG_DATA_HOME\fR or \fB$HOME/.local/share\fR, eg.
-.br
+\fB/home/alice/.local/share\fR
-eg. /home/alice/.local/share
 T}
-    macOS|T{
+    \fBmacOS\fR|T{
-\fI$HOME/Library/Application Support\fR
+\fB$HOME/Library/Application Support\fR, eg.
-.br
+\fB/Users/Alice/Library/Application Support\fR
-eg. /Users/Alice/Library/Application Support
 T}
-    Windows|T{
+    \fBWindows\fR|T{
-\fI{FOLDERID_RoamingAppData}\fR
+\fB{FOLDERID_RoamingAppData}\fR, eg. \fBC:\\Users\\Alice\\AppData\\Roaming\fR
-.br
-eg. C:\\Users\\Alice\\AppData\\Roaming
 T}
 .TE
 .TP
 .B _ZO_ECHO
-When set to \fI1\fR, z will print the matched directory before navigating
+When set to 1, \fBz\fR will print the matched directory before navigating to it.
-to it.
 .TP
 .B _ZO_EXCLUDE_DIRS
 Prevents the specified directories from being added to the database. This is
@@ -80,24 +75,24 @@ provided as a list of globs, separated by OS-specific characters:
 tab(|);
 l l.
     \fBOS|Separator\fR
-    Linux/macOS/BSD|T{
+    \fBLinux/macOS/BSD\fR|T{
-\fI:\fR eg. $HOME:$HOME/private/*
+\fB:\fR, eg. \fB$HOME:$HOME/private/*\fR
 T}
-    Windows|\fI;\fR eg. $HOME;$HOME/private/*
+    \fBWindows\fR|\fB;\fR, eg. \fB$HOME;$HOME/private/*\fR
 .TE
 .sp
-By default, this is set to \fI"$HOME"\fR. After setting this up, you might need
+By default, this is set to \fB$HOME\fR. After setting this up, you might need
 to use \fBzoxide-remove\fR(1) to remove any existing entries from the database.
 .TP
 .B _ZO_FZF_OPTS
-Custom options to pass to fzf. See \fBman fzf\fR for the list of options.
+Custom options to pass to fzf. See \fBfzf\fR(1) for the list of options.
 .TP
 .B _ZO_MAXAGE
 Configures the aging algorithm, which limits the maximum number of entries in
-the database. By default, this is set to \fI10000\fR.
+the database. By default, this is set to \fB10000\fR.
 .TP
 .B _ZO_RESOLVE_SYMLINKS
-When set to \fI1\fR, z will resolve symlinks before adding directories to
+When set to 1, \fBz\fR will resolve symlinks before adding directories to
 the database.
 .SH ALGORITHM
 .TP
@@ -105,48 +100,30 @@ the database.
 zoxide uses a parameter called \fB_ZO_MAXAGE\fR to limit the number of entries
 in the database based on usage patterns. If the total \fBFRECENCY\fR of the
 directories in the database exceeds this value, we divide each directory's
-score by a factor \fIk\fR such that the new total becomes ~90% of
+score by a factor \fBk\fR - such that the new total becomes ~90% of
 \fB_ZO_MAXAGE\fR. Thereafter, if the new score of any directory falls below
-\fI1\fR, it is removed from the database.
+1, it is removed from the database.
 .sp
 Theoretically, the maximum number of directories in the database is
-\fI4 * _ZO_MAXAGE\fR, although it is lower in practice.
+\fB4 * _ZO_MAXAGE\fR, although it is lower in practice.
 .TP
 .B FRECENCY
-Each directory in zoxide is given a score, starting with \fI1\fR the first time
+Each directory in zoxide is given a score, starting with 1 the first time
-it is accessed. Every subsequent access increases the score by \fI1\fR. When a
+it is accessed. Every subsequent access increases the score by 1. When a
 query is made, we calculate frecency based on the last time the directory was
 accessed:
 .TS
 tab(|);
 l l.
     \fBLast access time\fR|\fBFrecency\fR
-    Within the last hour|\fIscore * 4\fR
+    Within the last hour|score * 4
-    Within the last day|\fIscore * 2\fR
+    Within the last day|score * 2
-    Within the last week|\fIscore / 2\fR
+    Within the last week|score / 2
-    Otherwise|\fIscore / 4\fR
+    Otherwise|score / 4
 .TE
-.TP
-.B MATCHING
-zoxide uses a simple, predictable algorithm for resolving queries:
-.sp
-* All matching is case-insensitive.
-    \fBzoxide query\fR \fIfoo\fR matches \fI/foo\fR as well as \fI/FOO\fR.
-.sp
-* All terms must be present (including slashes) within the path, in order.
-    \fBzoxide query\fR \fIfo ba\fR matches \fI/foo/bar\fR, but not \fI/bar/foo\fR.
-    \fBzoxide query\fR \fIfo / ba\fR matches \fI/foo/bar\fR, but not \fI/foobar\fR.
-.sp
-* The last component of the last keyword must match the last component of the path.
-    \fBzoxide query\fR \fIbar\fR matches \fI/foo/bar\fR, but not \fI/bar/foo\fR.
-    \fBzoxide query\fR \fIfoo/bar\fR (last component: \fIbar\fR) matches \fI/foo/bar\fR, but not \fI/foo/bar/baz\fR.
-.sp
-* The path must exist. Deleted directories are filtered out.
-.sp
-* Matches are returned in descending order of \fBFRECENCY\fR.
 .SH REPORTING BUGS
 For any issues, feature requests, or questions, please visit:
 .sp
-    \fIhttps://github.com/ajeetdsouza/zoxide/issues\fR
+\fBhttps://github.com/ajeetdsouza/zoxide/issues\fR.
 .SH AUTHOR
-Ajeet D'Souza <\fI98ajeet@gmail.com\fR>
+Ajeet D'Souza <\fB98ajeet@gmail.com\fR>

shell.nix

@@ -18,8 +18,9 @@ pkgs.mkShell {
     pkgs.powershell
     pkgs.zsh
 
-    # Linters
+    # Tools
     pkgs-latest.cargo-audit
+    pkgs-latest.mandoc
     pkgs-latest.nodePackages.markdownlint-cli
     pkgs-latest.python3Packages.black
     pkgs-latest.python3Packages.mypy

src/shell.rs

@@ -41,7 +41,7 @@ make_template!(Powershell, "powershell.txt");
 make_template!(Xonsh, "xonsh.txt");
 make_template!(Zsh, "zsh.txt");
 
-#[cfg(feature = "shell_tests")]
+#[cfg(feature = "nix_tests")]
 #[cfg(test)]
 mod tests {
     use askama::Template;

tests/completion.rs

@@ -1,6 +1,6 @@
 //! Syntax checking for auto-generated shell completions.
+#![cfg(feature = "nix_tests")]
 
-#![cfg(feature = "shell_tests")]
 use assert_cmd::Command;
 
 #[test]

tests/man.rs

@@ -0,0 +1,28 @@
+//! Syntax checking for manpages.
+#![cfg(feature = "nix_tests")]
+
+use assert_cmd::Command;
+
+use std::fs;
+
+#[test]
+fn mandoc_lint() {
+    let paths = fs::read_dir("man")
+        .unwrap()
+        .filter_map(|entry| {
+            let path = entry.unwrap().path();
+            if path.is_file() && path.extension() == Some("1".as_ref()) {
+                Some(path.to_str().unwrap().to_string())
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<_>>();
+    Command::new("mandoc")
+        .args(&["-man", "-Wall", "-Tlint", "--"])
+        .args(&paths)
+        .assert()
+        .success()
+        .stdout("")
+        .stderr("");
+}