From 49f406e3ed54d9350f4822e34dcbad44e7fe00e1 Mon Sep 17 00:00:00 2001 From: Ajeet D'Souza <98ajeet@gmail.com> Date: Tue, 28 Sep 2021 04:52:27 +0530 Subject: [PATCH] Add linting for manpages --- Cargo.toml | 19 +------- man/zoxide-add.1 | 16 +++---- man/zoxide-import.1 | 18 ++++---- man/zoxide-init.1 | 29 ++++++------ man/zoxide-query.1 | 12 ++--- man/zoxide-remove.1 | 12 ++--- man/zoxide.1 | 105 +++++++++++++++++--------------------------- shell.nix | 3 +- src/shell.rs | 2 +- tests/completion.rs | 2 +- tests/man.rs | 28 ++++++++++++ 11 files changed, 118 insertions(+), 128 deletions(-) create mode 100644 tests/man.rs diff --git a/Cargo.toml b/Cargo.toml index e4873083..281f5d7f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -37,24 +37,7 @@ clap_generate = "=3.0.0-beta.4" [features] default = [] -# Adds tests for code generated by `zoxide init`. -# This requires the following external programs available in $PATH: -# - bash -# - black: -# - dash -# - elvish: -# - fish: -# - mypy: -# - nushell: -# - powershell: -# - pylint: -# - shellcheck: -# - shfmt: -# - xonsh: -# - zsh: -# Since most users are unlikely to have installed all of the above, these tests -# are disabled by default. -shell_tests = [] +nix_tests = [] [profile.release] codegen-units = 1 diff --git a/man/zoxide-add.1 b/man/zoxide-add.1 index d82b12ad..6e136bcd 100644 --- a/man/zoxide-add.1 +++ b/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 -existing score by \fI1\fR. It then sets the last updated field of the entry to the -current time. After this, it runs the \fBAGING\fR algorithm on the database. See +entry for it with a default score of 1, otherwise, it increments the existing +score by 1. It then sets the last updated field of the entry to the current +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> diff --git a/man/zoxide-import.1 b/man/zoxide-import.1 index d63a0974..3d3b262c 100644 --- a/man/zoxide-import.1 +++ b/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 - \fIz\fR|For \fIz\fR, \fIz.lua\fR, or \fIzsh-z\fR. + \fBautojump\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> diff --git a/man/zoxide-init.1 b/man/zoxide-init.1 index 3b61c402..0f1c314a 100644 --- a/man/zoxide-init.1 +++ b/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 - \fIprompt\fR|At every shell prompt - \fIpwd\fR|Whenever the directory is changed + \fBnone\fR|Never + \fBprompt\fR|At every shell prompt + \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> diff --git a/man/zoxide-query.1 b/man/zoxide-query.1 index 0db8e4cd..25f64256 100644 --- a/man/zoxide-query.1 +++ b/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> diff --git a/man/zoxide-remove.1 b/man/zoxide-remove.1 index ee716404..fa0c6dbe 100644 --- a/man/zoxide-remove.1 +++ b/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> diff --git a/man/zoxide.1 b/man/zoxide.1 index d38ac174..61949ebe 100644 --- a/man/zoxide.1 +++ b/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 - \fBz\fR \fIfoo bar\fR # cd into highest ranked directory matching foo and bar +$ z foo # cd into highest ranked directory matching foo +$ 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 - \fBz\fR \fIfoo/\fR # cd into relative path - \fBz\fR \fI..\fR # cd one level up - \fBz\fR \fI-\fR # cd into previous directory +$ z ~/foo # z also works like a regular cd command +$ z foo/ # cd into relative path +$ z .. # cd one level up +$ 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 -value varies across OSes: +Specifies the directory in which the database is stored. The default value +varies across OSes: .TS tab(|); l l. \fBOS|Path\fR - Linux/BSD|T{ -\fI$XDG_DATA_HOME\fR or \fI$HOME/.local/share\fR -.br -eg. /home/alice/.local/share + \fBLinux/BSD\fR|T{ +\fB$XDG_DATA_HOME\fR or \fB$HOME/.local/share\fR, eg. +\fB/home/alice/.local/share\fR T} - macOS|T{ -\fI$HOME/Library/Application Support\fR -.br -eg. /Users/Alice/Library/Application Support + \fBmacOS\fR|T{ +\fB$HOME/Library/Application Support\fR, eg. +\fB/Users/Alice/Library/Application Support\fR T} - Windows|T{ -\fI{FOLDERID_RoamingAppData}\fR -.br -eg. C:\\Users\\Alice\\AppData\\Roaming + \fBWindows\fR|T{ +\fB{FOLDERID_RoamingAppData}\fR, eg. \fBC:\\Users\\Alice\\AppData\\Roaming\fR T} .TE .TP .B _ZO_ECHO -When set to \fI1\fR, z will print the matched directory before navigating -to it. +When set to 1, \fBz\fR will print the matched directory before navigating 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{ -\fI:\fR eg. $HOME:$HOME/private/* + \fBLinux/macOS/BSD\fR|T{ +\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 -it is accessed. Every subsequent access increases the score by \fI1\fR. When a +Each directory in zoxide is given a score, starting with 1 the first time +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 day|\fIscore * 2\fR - Within the last week|\fIscore / 2\fR - Otherwise|\fIscore / 4\fR + Within the last hour|score * 4 + Within the last day|score * 2 + Within the last week|score / 2 + 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> diff --git a/shell.nix b/shell.nix index ab69b77b..dcee1a30 100644 --- a/shell.nix +++ b/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 diff --git a/src/shell.rs b/src/shell.rs index 9a4fe823..2b857990 100644 --- a/src/shell.rs +++ b/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; diff --git a/tests/completion.rs b/tests/completion.rs index 2db66e88..9887096d 100644 --- a/tests/completion.rs +++ b/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] diff --git a/tests/man.rs b/tests/man.rs new file mode 100644 index 00000000..6792fa1d --- /dev/null +++ b/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::>(); + Command::new("mandoc") + .args(&["-man", "-Wall", "-Tlint", "--"]) + .args(&paths) + .assert() + .success() + .stdout("") + .stderr(""); +}