Skip to content

Commit 4036c8f

Browse files
claudeclaude
committed
feat(man): add man page generation using clap_mangen
Add a `pdu-man-page` binary that generates a roff-formatted man page from the clap command definition. The generated `exports/pdu.1` file is kept in sync via a `sync_man_page` test, following the same pattern as completions and help text. Update generate-completions.sh, deploy CI, test matrix, and PKGBUILD templates to include the man page. https://claude.ai/code/session_01CrXuWDMVQsiUBoy6ceACsF
1 parent 5a88f61 commit 4036c8f

11 files changed

Lines changed: 218 additions & 1 deletion

File tree

‎.github/workflows/deploy.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,6 +271,16 @@ jobs:
271271
asset_name: completion.elv
272272
asset_content_type: text/plain
273273

274+
- name: Upload Man Page
275+
uses: actions/upload-release-asset@v1.0.2
276+
env:
277+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
278+
with:
279+
upload_url: ${{ needs.create_release.outputs.upload_url }}
280+
asset_path: ./exports/pdu.1
281+
asset_name: pdu.1
282+
asset_content_type: text/plain
283+
274284
upload_release_assets:
275285
name: Upload Release Assets
276286

‎Cargo.lock‎

Lines changed: 17 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,11 @@ name = "pdu-completions"
4444
path = "cli/completions.rs"
4545
required-features = ["cli-completions"]
4646

47+
[[bin]]
48+
name = "pdu-man-page"
49+
path = "cli/man_page.rs"
50+
required-features = ["cli-man"]
51+
4752
[[bin]]
4853
name = "pdu-usage-md"
4954
path = "cli/usage_md.rs"
@@ -59,12 +64,14 @@ default = ["cli"]
5964
json = ["serde/derive", "serde_json"]
6065
cli = ["clap/derive", "clap_complete", "clap-utilities", "json"]
6166
cli-completions = ["cli"]
67+
cli-man = ["cli", "clap_mangen"]
6268
ai-instructions = ["clap/derive"]
6369

6470
[dependencies]
6571
assert-cmp = "0.3.0"
6672
clap = { version = "4.5.60", optional = true }
6773
clap_complete = { version = "4.5.66", optional = true }
74+
clap_mangen = { version = "0.2.27", optional = true }
6875
clap-utilities = { version = "0.3.0", optional = true }
6976
dashmap = "6.1.0"
7077
derive_more = { version = "2.1.1", features = ["full"] }
@@ -85,6 +92,7 @@ zero-copy-pads = "0.2.0"
8592

8693
[dev-dependencies]
8794
build-fs-tree = "0.8.1"
95+
clap_mangen = "0.2.27"
8896
command-extra = "1.0.0"
8997
libc = "0.2.182"
9098
maplit = "1.0.2"

‎cli/man_page.rs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
use clap::CommandFactory;
2+
use clap_mangen::Man;
3+
use parallel_disk_usage::args::Args;
4+
use std::{io::stdout, process::ExitCode};
5+
6+
fn main() -> ExitCode {
7+
let command = Args::command();
8+
let man = Man::new(command);
9+
match man.render(&mut stdout()) {
10+
Ok(()) => ExitCode::SUCCESS,
11+
Err(error) => {
12+
eprintln!("error: {error}");
13+
ExitCode::FAILURE
14+
}
15+
}
16+
}

‎exports/pdu.1‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
.ie \n(.g .ds Aq \(aq
2+
.el .ds Aq '
3+
.TH pdu 1 "pdu 0.21.1"
4+
.SH NAME
5+
pdu \- Summarize disk usage of the set of files, recursively for directories.
6+
.SH SYNOPSIS
7+
\fBpdu\fR [\fB\-\-json\-input\fR] [\fB\-\-json\-output\fR] [\fB\-b\fR|\fB\-\-bytes\-format\fR] [\fB\-H\fR|\fB\-\-deduplicate\-hardlinks\fR] [\fB\-x\fR|\fB\-\-one\-file\-system\fR] [\fB\-\-top\-down\fR] [\fB\-\-align\-right\fR] [\fB\-q\fR|\fB\-\-quantity\fR] [\fB\-d\fR|\fB\-\-max\-depth\fR] [\fB\-w\fR|\fB\-\-total\-width\fR] [\fB\-\-column\-width\fR] [\fB\-m\fR|\fB\-\-min\-ratio\fR] [\fB\-\-no\-sort\fR] [\fB\-s\fR|\fB\-\-silent\-errors\fR] [\fB\-p\fR|\fB\-\-progress\fR] [\fB\-\-threads\fR] [\fB\-\-omit\-json\-shared\-details\fR] [\fB\-\-omit\-json\-shared\-summary\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fIFILES\fR]
8+
.SH DESCRIPTION
9+
Summarize disk usage of the set of files, recursively for directories.
10+
.PP
11+
Copyright: Apache\-2.0 © 2021 Hoàng Văn Khải <https://github.com/KSXGitHub/>
12+
Sponsor: https://github.com/sponsors/KSXGitHub
13+
.SH OPTIONS
14+
.TP
15+
\fB\-\-json\-input\fR
16+
Read JSON data from stdin
17+
.TP
18+
\fB\-\-json\-output\fR
19+
Print JSON data instead of an ASCII chart
20+
.TP
21+
\fB\-b\fR, \fB\-\-bytes\-format\fR \fI<BYTES_FORMAT>\fR [default: metric]
22+
How to display the numbers of bytes
23+
.br
24+
25+
.br
26+
\fIPossible values:\fR
27+
.RS 14
28+
.IP \(bu 2
29+
plain: Display plain number of bytes without units
30+
.IP \(bu 2
31+
metric: Use metric scale, i.e. 1K = 1000B, 1M = 1000K, and so on
32+
.IP \(bu 2
33+
binary: Use binary scale, i.e. 1K = 1024B, 1M = 1024K, and so on
34+
.RE
35+
.TP
36+
\fB\-H\fR, \fB\-\-deduplicate\-hardlinks\fR
37+
Detect and subtract the sizes of hardlinks from their parent directory totals
38+
.TP
39+
\fB\-x\fR, \fB\-\-one\-file\-system\fR
40+
Skip directories on different filesystems
41+
.TP
42+
\fB\-\-top\-down\fR
43+
Print the tree top\-down instead of bottom\-up
44+
.TP
45+
\fB\-\-align\-right\fR
46+
Set the root of the bars to the right
47+
.TP
48+
\fB\-q\fR, \fB\-\-quantity\fR \fI<QUANTITY>\fR [default: block\-size]
49+
Aspect of the files/directories to be measured
50+
.br
51+
52+
.br
53+
\fIPossible values:\fR
54+
.RS 14
55+
.IP \(bu 2
56+
apparent\-size: Measure apparent sizes
57+
.IP \(bu 2
58+
block\-size: Measure block sizes (block\-count * 512B)
59+
.IP \(bu 2
60+
block\-count: Count numbers of blocks
61+
.RE
62+
.TP
63+
\fB\-d\fR, \fB\-\-max\-depth\fR \fI<MAX_DEPTH>\fR [default: 10]
64+
Maximum depth to display the data. Could be either "inf" or a positive integer
65+
.TP
66+
\fB\-w\fR, \fB\-\-total\-width\fR \fI<TOTAL_WIDTH>\fR
67+
Width of the visualization
68+
.TP
69+
\fB\-\-column\-width\fR \fI<TREE_WIDTH>\fR\fI \fR\fI<BAR_WIDTH>\fR
70+
Maximum widths of the tree column and width of the bar column
71+
.TP
72+
\fB\-m\fR, \fB\-\-min\-ratio\fR \fI<MIN_RATIO>\fR [default: 0.01]
73+
Minimal size proportion required to appear
74+
.TP
75+
\fB\-\-no\-sort\fR
76+
Do not sort the branches in the tree
77+
.TP
78+
\fB\-s\fR, \fB\-\-silent\-errors\fR
79+
Prevent filesystem error messages from appearing in stderr
80+
.TP
81+
\fB\-p\fR, \fB\-\-progress\fR
82+
Report progress being made at the expense of performance
83+
.TP
84+
\fB\-\-threads\fR \fI<THREADS>\fR [default: auto]
85+
Set the maximum number of threads to spawn. Could be either "auto", "max", or a positive integer
86+
.TP
87+
\fB\-\-omit\-json\-shared\-details\fR
88+
Do not output `.shared.details` in the JSON output
89+
.TP
90+
\fB\-\-omit\-json\-shared\-summary\fR
91+
Do not output `.shared.summary` in the JSON output
92+
.TP
93+
\fB\-h\fR, \fB\-\-help\fR
94+
Print help (see a summary with \*(Aq\-h\*(Aq)
95+
.TP
96+
\fB\-V\fR, \fB\-\-version\fR
97+
Print version
98+
.TP
99+
[\fIFILES\fR]
100+
List of files and/or directories
101+
.SH EXTRA
102+
Examples:
103+
Show disk usage chart of current working directory
104+
$ pdu
105+
106+
Show disk usage chart of a single file or directory
107+
$ pdu path/to/file/or/directory
108+
109+
Compare disk usages of multiple files and/or directories
110+
$ pdu file.txt dir/
111+
112+
Show chart in apparent sizes instead of block sizes
113+
$ pdu \-\-quantity=apparent\-size
114+
115+
Detect and subtract the sizes of hardlinks from their parent nodes
116+
$ pdu \-\-deduplicate\-hardlinks
117+
118+
Show sizes in plain numbers instead of metric units
119+
$ pdu \-\-bytes\-format=plain
120+
121+
Show sizes in base 2¹⁰ units (binary) instead of base 10³ units (metric)
122+
$ pdu \-\-bytes\-format=binary
123+
124+
Show disk usage chart of all entries regardless of size
125+
$ pdu \-\-min\-ratio=0
126+
127+
Only show disk usage chart of entries whose size is at least 5% of total
128+
$ pdu \-\-min\-ratio=0.05
129+
130+
Show disk usage data as JSON instead of chart
131+
$ pdu \-\-min\-ratio=0 \-\-max\-depth=inf \-\-json\-output | jq
132+
133+
Visualize existing JSON representation of disk usage data
134+
$ pdu \-\-json\-input < disk\-usage.json
135+
.SH VERSION
136+
v0.21.1

‎generate-completions.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ gen elvish completion.elv
1717
./run.sh pdu --help | sed 's/[[:space:]]*$//' > exports/long.help
1818
./run.sh pdu -h | sed 's/[[:space:]]*$//' > exports/short.help
1919
./run.sh pdu-usage-md > USAGE.md
20+
./run.sh pdu-man-page > exports/pdu.1

‎run.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
#! /bin/bash
22
set -o errexit -o pipefail -o nounset
3-
exec cargo run --bin="$1" --features cli-completions,ai-instructions -- "${@:2}"
3+
exec cargo run --bin="$1" --features cli-completions,cli-man,ai-instructions -- "${@:2}"

‎template/parallel-disk-usage-bin/PKGBUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,5 @@ package() {
2121
install -Dm644 "completion.$pkgver.bash" "$pkgdir/usr/share/bash-completion/completions/pdu"
2222
install -Dm644 "completion.$pkgver.fish" "$pkgdir/usr/share/fish/completions/pdu.fish"
2323
install -Dm644 "completion.$pkgver.zsh" "$pkgdir/usr/share/zsh/site-functions/_pdu"
24+
install -Dm644 "pdu.$pkgver.1" "$pkgdir/usr/share/man/man1/pdu.1"
2425
}

‎template/parallel-disk-usage/PKGBUILD‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,5 @@ package() {
2020
install -Dm644 exports/completion.bash "$pkgdir/usr/share/bash-completion/completions/pdu"
2121
install -Dm644 exports/completion.fish "$pkgdir/usr/share/fish/completions/pdu.fish"
2222
install -Dm644 exports/completion.zsh "$pkgdir/usr/share/zsh/site-functions/_pdu"
23+
install -Dm644 exports/pdu.1 "$pkgdir/usr/share/man/man1/pdu.1"
2324
}

‎test.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ unit --no-default-features "$@"
7777
unit --all-features "$@"
7878
unit --features cli "$@"
7979
unit --features cli-completions "$@"
80+
unit --features cli-man "$@"
8081
unit --features ai-instructions "$@"
8182

8283
if [[ -f "$failure_marker" ]]; then

0 commit comments

Comments
 (0)