From 268c62b66d46e033786612ce1e85c3c8ee21933a Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Wed, 8 Apr 2020 12:19:50 -0700 Subject: [PATCH] Add `bin/man` command for generating man pages Generates man pages and book entries for all subcommands, and keeps the commands index in the book up to date. There is much cursed roff munging in this diff. type: documentation --- CHANGELOG.md | 5 +- Cargo.lock | 10 ++ Cargo.toml | 3 + bin/man/Cargo.toml | 12 ++ bin/man/src/bin.rs | 38 +++++ bin/man/src/common.rs | 12 ++ bin/man/src/main.rs | 57 +++++++ bin/man/src/subcommand.rs | 149 +++++++++++++++++ book/book.toml | 16 +- book/src/SUMMARY.md | 11 ++ book/src/commands.md | 4 + book/src/commands/imdl-completions.md | 16 ++ book/src/commands/imdl-torrent-create.md | 106 ++++++++++++ book/src/commands/imdl-torrent-link.md | 20 +++ .../src/commands/imdl-torrent-piece-length.md | 13 ++ book/src/commands/imdl-torrent-show.md | 17 ++ book/src/commands/imdl-torrent-stats.md | 25 +++ book/src/commands/imdl-torrent-verify.md | 19 +++ book/src/commands/imdl-torrent.md | 22 +++ book/src/commands/imdl.md | 28 ++++ justfile | 19 ++- man/imdl-completions.1 | 19 +++ man/imdl-torrent-create.1 | 157 ++++++++++++++++++ man/imdl-torrent-link.1 | 27 +++ man/imdl-torrent-piece-length.1 | 15 ++ man/imdl-torrent-show.1 | 20 +++ man/imdl-torrent-stats.1 | 34 ++++ man/imdl-torrent-verify.1 | 24 +++ man/imdl-torrent.1 | 37 +++++ man/imdl.1 | 29 ++-- 30 files changed, 933 insertions(+), 31 deletions(-) create mode 100644 bin/man/Cargo.toml create mode 100644 bin/man/src/bin.rs create mode 100644 bin/man/src/common.rs create mode 100644 bin/man/src/main.rs create mode 100644 bin/man/src/subcommand.rs create mode 100644 book/src/commands.md create mode 100644 book/src/commands/imdl-completions.md create mode 100644 book/src/commands/imdl-torrent-create.md create mode 100644 book/src/commands/imdl-torrent-link.md create mode 100644 book/src/commands/imdl-torrent-piece-length.md create mode 100644 book/src/commands/imdl-torrent-show.md create mode 100644 book/src/commands/imdl-torrent-stats.md create mode 100644 book/src/commands/imdl-torrent-verify.md create mode 100644 book/src/commands/imdl-torrent.md create mode 100644 book/src/commands/imdl.md create mode 100644 man/imdl-completions.1 create mode 100644 man/imdl-torrent-create.1 create mode 100644 man/imdl-torrent-link.1 create mode 100644 man/imdl-torrent-piece-length.1 create mode 100644 man/imdl-torrent-show.1 create mode 100644 man/imdl-torrent-stats.1 create mode 100644 man/imdl-torrent-verify.1 create mode 100644 man/imdl-torrent.1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 39943ec..7016616 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,10 @@ Changelog ========= -UNRELEASED - 2020-04-08 +UNRELEASED - 2020-04-09 ----------------------- -- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Make smaller demo for readme (#346) - _Casey Rodarmor _ +- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Add `bin/man` command for generating man pages - _Casey Rodarmor _ +- :books: [`14fff1d888a3`](https://github.com/casey/intermodal/commit/14fff1d888a3d4aebd88059feacde5c665019f30) Make smaller demo for readme - _Casey Rodarmor _ - :books: [`4f8b6a212e80`](https://github.com/casey/intermodal/commit/4f8b6a212e8099ebfcf14600ce92863583758231) Improve demo GIF - _Casey Rodarmor _ diff --git a/Cargo.lock b/Cargo.lock index ded0c62..c838dd0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -532,6 +532,16 @@ dependencies = [ "cfg-if", ] +[[package]] +name = "man" +version = "0.0.0" +dependencies = [ + "anyhow", + "fehler", + "regex", + "tempfile", +] + [[package]] name = "matches" version = "0.1.8" diff --git a/Cargo.toml b/Cargo.toml index 944fce0..03275fd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -70,4 +70,7 @@ members = [ # generate the changelog from git commits "bin/changelog", + + # generate man page + "bin/man" ] diff --git a/bin/man/Cargo.toml b/bin/man/Cargo.toml new file mode 100644 index 0000000..76b84f5 --- /dev/null +++ b/bin/man/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "man" +version = "0.0.0" +authors = ["Casey Rodarmor "] +edition = "2018" +publish = false + +[dependencies] +anyhow = "1.0.28" +fehler = "1.0.0" +tempfile = "3.1.0" +regex = "1.3.6" diff --git a/bin/man/src/bin.rs b/bin/man/src/bin.rs new file mode 100644 index 0000000..326cb07 --- /dev/null +++ b/bin/man/src/bin.rs @@ -0,0 +1,38 @@ +use crate::common::*; + +#[derive(Debug)] +pub(crate) struct Bin { + pub(crate) bin: String, + pub(crate) subcommands: Vec, +} + +impl Bin { + #[throws] + pub(crate) fn new(bin: &str) -> Self { + let mut bin = Bin { + bin: bin.into(), + subcommands: Vec::new(), + }; + + bin.add_subcommands(&mut Vec::new())?; + + bin.subcommands.sort(); + + bin + } + + #[throws] + fn add_subcommands(&mut self, command: &mut Vec) { + let subcommand = Subcommand::new(&self.bin, command.clone())?; + + for name in &subcommand.subcommands { + command.push(name.into()); + if name != "help" { + self.add_subcommands(command)?; + } + command.pop(); + } + + self.subcommands.push(subcommand); + } +} diff --git a/bin/man/src/common.rs b/bin/man/src/common.rs new file mode 100644 index 0000000..ca7406e --- /dev/null +++ b/bin/man/src/common.rs @@ -0,0 +1,12 @@ +pub(crate) use std::{ + fs, + path::Path, + process::{Command, Stdio}, + str, +}; + +pub(crate) use anyhow::{anyhow, Error}; +pub(crate) use fehler::{throw, throws}; +pub(crate) use regex::Regex; + +pub(crate) use crate::{bin::Bin, subcommand::Subcommand}; diff --git a/bin/man/src/main.rs b/bin/man/src/main.rs new file mode 100644 index 0000000..5716e47 --- /dev/null +++ b/bin/man/src/main.rs @@ -0,0 +1,57 @@ +use crate::common::*; + +mod bin; +mod common; +mod subcommand; + +#[throws] +fn clean(dir: impl AsRef) { + let dir = dir.as_ref(); + fs::remove_dir_all(dir)?; + fs::create_dir_all(dir)?; +} + +#[throws] +fn write(dst: impl AsRef, contents: &str) { + let dst = dst.as_ref(); + println!("Writing `{}`…", dst.display()); + fs::write(dst, contents)?; +} + +#[throws] +fn main() { + let bin = Bin::new("target/debug/imdl")?; + + clean("man")?; + clean("book/src/commands")?; + + let mut pages = "- [Commands](./commands.md)\n".to_string(); + + for subcommand in bin.subcommands { + let slug = subcommand.slug(); + + let dst = format!("man/{}.1", slug); + write(dst, &subcommand.man)?; + + let dst = format!("book/src/commands/{}.md", slug); + write(dst, &subcommand.page())?; + + pages.push_str(&format!( + " - [`{}`](./commands/{}.md)\n", + subcommand.command_line(), + slug + )) + } + + pages.push('\n'); + + let path = "book/src/SUMMARY.md"; + + let original = fs::read_to_string(path)?; + + let re = Regex::new(r"(?ms)^- \[Commands\]\(./commands.md\).*?\n\n").unwrap(); + + let text = re.replace(&original, pages.as_str()).into_owned(); + + fs::write(path, text)?; +} diff --git a/bin/man/src/subcommand.rs b/bin/man/src/subcommand.rs new file mode 100644 index 0000000..fb7a132 --- /dev/null +++ b/bin/man/src/subcommand.rs @@ -0,0 +1,149 @@ +use crate::common::*; + +#[derive(Debug, Ord, PartialOrd, Eq, PartialEq)] +pub(crate) struct Subcommand { + pub(crate) bin: String, + pub(crate) command: Vec, + pub(crate) help: String, + pub(crate) man: String, + pub(crate) subcommands: Vec, +} + +trait CommandExt { + #[throws] + fn out(&mut self) -> String; +} + +impl CommandExt for Command { + #[throws] + fn out(&mut self) -> String { + let output = self.stdout(Stdio::piped()).output()?; + + if !output.status.success() { + throw!(anyhow!("Command `{:?}` failed: {}", self, output.status)); + } + + let text = String::from_utf8(output.stdout)?; + + text + } +} + +impl Subcommand { + #[throws] + pub(crate) fn new(bin: &str, command: Vec) -> Self { + let help = Command::new(bin) + .args(command.as_slice()) + .arg("--help") + .out()?; + + const MARKER: &str = "\nSUBCOMMANDS:\n"; + + let mut subcommands = Vec::new(); + + if let Some(marker) = help.find(MARKER) { + let block = &help[marker + MARKER.len()..]; + + for line in block.lines() { + let name = line.trim().split_whitespace().next().unwrap(); + subcommands.push(name.into()); + } + } + + let command_line = format!("{} {}", bin, command.join(" ")); + + let name = command_line + .split('/') + .last() + .unwrap() + .trim() + .replace(" ", "\\ "); + + let description = if command.is_empty() { + "A 40' shipping container for the Internet".to_string() + } else { + help.lines().nth(1).unwrap().into() + }; + + let include = format!( + "\ +[NAME] +\\fB{}\\fR +- {} +", + name, description + ); + + let tmp = tempfile::tempdir()?; + + fs::write(tmp.path().join("include"), include)?; + + let include = tmp.path().join("include").to_string_lossy().into_owned(); + + let version = Command::new(bin) + .arg("--version") + .out()? + .split_whitespace() + .nth(1) + .unwrap() + .to_owned(); + + let output = Command::new("help2man") + .args(&[ + "--include", + &include, + "--manual", + "Intermodal Manual", + "--no-info", + "--source", + &format!("Intermodal {}", version), + ]) + .arg(&command_line) + .stdout(Stdio::piped()) + .output()?; + + if !output.status.success() { + throw!(anyhow!( + "Failed to generate man page for `{}` failed: {}", + command_line, + output.status + )); + } + + let man = str::from_utf8(&output.stdout)? + .replace("📦 ", "\n") + .replace("\n.SS ", "\n.SH ") + .replace("\"USAGE:\"", "\"SYNOPSIS:\""); + + let re = Regex::new(r"(?ms).SH DESCRIPTION.*?.SH").unwrap(); + + let man = re.replace(&man, ".SH").into_owned(); + + Self { + bin: bin.into(), + command, + help, + man, + subcommands, + } + } + + pub(crate) fn slug(&self) -> String { + let mut slug = self.bin.split('/').last().unwrap().to_owned(); + + for name in &self.command { + slug.push('-'); + slug.push_str(&name); + } + + slug + } + + pub(crate) fn command_line(&self) -> String { + self.slug().replace('-', " ") + } + + pub(crate) fn page(&self) -> String { + format!("# `{}`\n```\n{}\n```", self.command_line(), self.help) + } +} diff --git a/book/book.toml b/book/book.toml index d082f45..6b3612b 100644 --- a/book/book.toml +++ b/book/book.toml @@ -1,9 +1,13 @@ [book] -authors = ["Casey Rodarmor"] -language = "en" -multilingual = false -src = "src" -title = "Intermodal" +authors = ["Casey Rodarmor"] +create-missing = false +language = "en" +multilingual = false +src = "src" +title = "Intermodal" [output.html] -additional-css = ["custom.css"] +additional-css = ["custom.css"] +curly-quotes = true +default-theme = "ayu" +git-repository-url = "https://github.com/casey/intermodal" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index b4f85a5..671830e 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -3,6 +3,17 @@ Summary [Intermodal](./introduction.md) +- [Commands](./commands.md) + - [`imdl`](./commands/imdl.md) + - [`imdl completions`](./commands/imdl-completions.md) + - [`imdl torrent`](./commands/imdl-torrent.md) + - [`imdl torrent create`](./commands/imdl-torrent-create.md) + - [`imdl torrent link`](./commands/imdl-torrent-link.md) + - [`imdl torrent piece length`](./commands/imdl-torrent-piece-length.md) + - [`imdl torrent show`](./commands/imdl-torrent-show.md) + - [`imdl torrent stats`](./commands/imdl-torrent-stats.md) + - [`imdl torrent verify`](./commands/imdl-torrent-verify.md) + - [Bittorrent](./bittorrent.md) - [BEP Support](./bittorrent/bep-support.md) - [Alternatives & Prior Art](./bittorrent/prior-art.md) diff --git a/book/src/commands.md b/book/src/commands.md new file mode 100644 index 0000000..f5e403c --- /dev/null +++ b/book/src/commands.md @@ -0,0 +1,4 @@ +Commands +======== + +This page intentionally left blank. diff --git a/book/src/commands/imdl-completions.md b/book/src/commands/imdl-completions.md new file mode 100644 index 0000000..18924b1 --- /dev/null +++ b/book/src/commands/imdl-completions.md @@ -0,0 +1,16 @@ +# `imdl completions` +``` +imdl-completions 0.1.2 +Print shell completion scripts to standard output. + +USAGE: + imdl completions --shell + +FLAGS: + -h, --help Print help message. + -V, --version Print version number. + +OPTIONS: + -s, --shell Print completions for `SHELL`. [possible values: zsh, bash, fish, powershell, elvish] + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-create.md b/book/src/commands/imdl-torrent-create.md new file mode 100644 index 0000000..3c043b2 --- /dev/null +++ b/book/src/commands/imdl-torrent-create.md @@ -0,0 +1,106 @@ +# `imdl torrent create` +``` +imdl-torrent-create 0.1.2 +Create a `.torrent` file. + +USAGE: + imdl torrent create [FLAGS] [OPTIONS] --input + +FLAGS: + -n, --dry-run Skip writing `.torrent` file to disk. + -F, --follow-symlinks Follow symlinks in torrent input. By default, symlinks to files and directories are not + included in torrent contents. + -f, --force Overwrite the destination `.torrent` file, if it exists. + --help Print help message. + -h, --include-hidden Include hidden files that would otherwise be skipped, such as files that start with a `.`, + and files hidden by file attributes on macOS and Windows. + -j, --include-junk Include junk files that would otherwise be skipped. + -M, --md5 Include MD5 checksum of each file in the torrent. N.B. MD5 is cryptographically broken and + only suitable for checking for accidental corruption. + --no-created-by Do not populate `created by` key of generated torrent with imdl version information. + --no-creation-date Do not populate `creation date` key of generated torrent with current time. + -O, --open Open `.torrent` file after creation. Uses `xdg-open`, `gnome-open`, or `kde-open` on + Linux; `open` on macOS; and `cmd /C start` on Windows + --link Print created torrent `magnet:` URL to standard output + -P, --private Set the `private` flag. Torrent clients that understand the flag and participate in the + swarm of a torrent with the flag set will only announce themselves to the announce URLs + included in the torrent, and will not use other peer discovery mechanisms, such as the DHT + or local peer discovery. See BEP 27: Private Torrents for more information. + -S, --show Display information about created torrent file. + -V, --version Print version number. + +OPTIONS: + -A, --allow ... Allow `LINT`. Lints check for conditions which, although permitted, are not + usually desirable. For example, piece length can be any non-zero value, but + probably shouldn't be below 16 KiB. The lint `small-piece-size` checks for + this, and `--allow small-piece-size` can be used to disable this check. + [possible values: private-trackerless, small-piece-length, uneven-piece-length] + -a, --announce Use `URL` as the primary tracker announce URL. To supply multiple announce + URLs, also use `--announce-tier`. + -t, --announce-tier ... Use `URL-LIST` as a tracker announce tier. Each instance adds a new tier. To + add multiple trackers to a given tier, separate their announce URLs with + commas: + + `--announce-tier + udp://example.com:80/announce,https://example.net:443/announce` + + Announce tiers are stored in the `announce-list` key of the top-level metainfo + dictionary as a list of lists of strings, as defined by BEP 12: Multitracker + Metadata Extension. + + Note: Many BitTorrent clients do not implement the behavior described in BEP + 12. See the discussion here for more details: + https://github.com/bittorrent/bittorrent.org/issues/82 + -c, --comment Include `TEXT` as the comment for generated `.torrent` file. Stored under + `comment` key of top-level metainfo dictionary. + --node ... Add DHT bootstrap node `NODE` to torrent. `NODE` should be in the form + `HOST:PORT`, where `HOST` is a domain name, an IPv4 address, or an IPv6 address + surrounded by brackets. May be given more than once to add multiple bootstrap + nodes. + + Examples: + + --node router.example.com:1337 + + --node 203.0.113.0:2290 + + --node [2001:db8:4275:7920:6269:7463:6f69:6e21]:8832 + -g, --glob ... Include or exclude files that match `GLOB`. Multiple glob may be provided, with + the last one taking precedence. Precede a glob with `!` to exclude it. + -i, --input Read torrent contents from `PATH`. If `PATH` is a file, torrent will be a + single-file torrent. If `PATH` is a directory, torrent will be a multi-file + torrent. If `PATH` is `-`, read from standard input. Piece length defaults to + 256KiB when reading from standard input if `--piece-length` is not given. + -N, --name Set name of torrent to `TEXT`. Defaults to the filename of the argument to + `--input`. Required when `--input -`. + -o, --output Save `.torrent` file to `TARGET`, or print to standard output if `TARGET` is + `-`. Defaults to the argument to `--input` with an `.torrent` extension + appended. Required when `--input -`. + --peer ... Add `PEER` to magnet link. + -p, --piece-length Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and gib. + --sort-by ... Set the order of files within a torrent. `SPEC` should be of the form + `KEY:ORDER`, with `KEY` being one of `path` or `size`, and `ORDER` being + `ascending` or `descending`. `:ORDER` defaults to `ascending` if omitted. The + `--sort-by` flag may be given more than once, with later values being used to + break ties. Ties that remain are broken in ascending path order. + + Sort in ascending order by path, the default: + + --sort-by path:ascending + + Sort in ascending order by path, more concisely: + + --sort-by path + + Sort in ascending order by size, break ties in descending path order: + + --sort-by size:ascending --sort-by path:descending + -s, --source Set torrent source to `TEXT`. Stored under `source` key of info dictionary. + This is useful for keeping statistics from being mis-reported when + participating in swarms with the same contents, but with different trackers. + When source is set to a unique value for torrents with the same contents, + torrent clients will treat them as distinct torrents, and not share peers + between them, and will correctly report download and upload statistics to + multiple trackers. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-link.md b/book/src/commands/imdl-torrent-link.md new file mode 100644 index 0000000..10ecd9a --- /dev/null +++ b/book/src/commands/imdl-torrent-link.md @@ -0,0 +1,20 @@ +# `imdl torrent link` +``` +imdl-torrent-link 0.1.2 +Generate a magnet link from a `.torrent` file. + +USAGE: + imdl torrent link [FLAGS] [OPTIONS] --input + +FLAGS: + -h, --help Print help message. + -O, --open Open generated magnet link. Uses `xdg-open`, `gnome-open`, or `kde-open` on Linux; `open` on macOS; + and `cmd /C start` on Windows + -V, --version Print version number. + +OPTIONS: + -i, --input Generate magnet link from metainfo at `PATH`. If `PATH` is `-`, read metainfo from + standard input. + -p, --peer ... Add `PEER` to magnet link. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-piece-length.md b/book/src/commands/imdl-torrent-piece-length.md new file mode 100644 index 0000000..6ac4d3a --- /dev/null +++ b/book/src/commands/imdl-torrent-piece-length.md @@ -0,0 +1,13 @@ +# `imdl torrent piece length` +``` +imdl-torrent-piece-length 0.1.2 +Display information about automatic piece length selection. + +USAGE: + imdl torrent piece-length + +FLAGS: + -h, --help Print help message. + -V, --version Print version number. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-show.md b/book/src/commands/imdl-torrent-show.md new file mode 100644 index 0000000..86d9e29 --- /dev/null +++ b/book/src/commands/imdl-torrent-show.md @@ -0,0 +1,17 @@ +# `imdl torrent show` +``` +imdl-torrent-show 0.1.2 +Display information about a `.torrent` file. + +USAGE: + imdl torrent show --input + +FLAGS: + -h, --help Print help message. + -V, --version Print version number. + +OPTIONS: + -i, --input Show information about torrent at `PATH`. If `Path` is `-`, read torrent metainfo from + standard input. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-stats.md b/book/src/commands/imdl-torrent-stats.md new file mode 100644 index 0000000..64fa52a --- /dev/null +++ b/book/src/commands/imdl-torrent-stats.md @@ -0,0 +1,25 @@ +# `imdl torrent stats` +``` +imdl-torrent-stats 0.1.2 +Show statistics about a collection of `.torrent` files. + +USAGE: + imdl torrent stats [FLAGS] [OPTIONS] --input + +FLAGS: + -h, --help Print help message. + -p, --print Pretty print the contents of each torrent as it is processed. + -V, --version Print version number. + +OPTIONS: + -e, --extract-pattern ... Extract and display values under key paths that match `REGEX`. Subkeys of a + bencodeded dictionary are delimited by `/`, and values of a bencoded list are + delmited by `*`. For example, given the following bencoded dictionary `{"foo": + [{"bar": {"baz": 2}}]}`, the value `2`'s key path will be `foo*bar/baz`. The + value `2` would be displayed if any of `bar`, `foo[*]bar/baz`, or `foo.*baz` + were passed to `--extract-pattern. + -i, --input Search `PATH` for torrents. May be a directory or a single torrent file. + -l, --limit Stop after processing `N` torrents. Useful when processing large collections of + `.torrent` files. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent-verify.md b/book/src/commands/imdl-torrent-verify.md new file mode 100644 index 0000000..e9419e3 --- /dev/null +++ b/book/src/commands/imdl-torrent-verify.md @@ -0,0 +1,19 @@ +# `imdl torrent verify` +``` +imdl-torrent-verify 0.1.2 +Verify files against a `.torrent` file. + +USAGE: + imdl torrent verify [OPTIONS] --input + +FLAGS: + -h, --help Print help message. + -V, --version Print version number. + +OPTIONS: + -c, --content Verify torrent content at `PATH` against torrent metainfo. Defaults to `name` field of + torrent info dictionary. + -i, --input Verify torrent contents against torrent metainfo in `METAINFO`. If `METAINFO` is `-`, read + metainfo from standard input. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl-torrent.md b/book/src/commands/imdl-torrent.md new file mode 100644 index 0000000..e0ddf6b --- /dev/null +++ b/book/src/commands/imdl-torrent.md @@ -0,0 +1,22 @@ +# `imdl torrent` +``` +imdl-torrent 0.1.2 +Subcommands related to the BitTorrent protocol. + +USAGE: + imdl torrent + +FLAGS: + -h, --help Print help message. + -V, --version Print version number. + +SUBCOMMANDS: + create Create a `.torrent` file. + help Prints this message or the help of the given subcommand(s) + link Generate a magnet link from a `.torrent` file. + piece-length Display information about automatic piece length selection. + show Display information about a `.torrent` file. + stats Show statistics about a collection of `.torrent` files. + verify Verify files against a `.torrent` file. + +``` \ No newline at end of file diff --git a/book/src/commands/imdl.md b/book/src/commands/imdl.md new file mode 100644 index 0000000..297f642 --- /dev/null +++ b/book/src/commands/imdl.md @@ -0,0 +1,28 @@ +# `imdl` +``` +imdl v0.1.2 +Casey Rodarmor +📦 A 40' shipping container for the internet - https://github.com/casey/intermodal + +USAGE: + imdl [FLAGS] [OPTIONS] + +FLAGS: + -h, --help Print help message. + -u, --unstable Enable unstable features. To avoid premature stabilization and excessive version churn, unstable + features are unavailable unless this flag is set. Unstable features are not bound by semantic + versioning stability guarantees, and may be changed or removed at any time. + -V, --version Print version number. + +OPTIONS: + --color Print colorful output according to `WHEN`. When `auto`, the default, colored output is only + enabled if imdl detects that it is connected to a terminal, the `NO_COLOR` environment + variable is not set, and the `TERM` environment variable is not set to `dumb`. [default: auto] + [possible values: auto, always, never] + +SUBCOMMANDS: + completions Print shell completion scripts to standard output. + help Prints this message or the help of the given subcommand(s) + torrent Subcommands related to the BitTorrent protocol. + +``` \ No newline at end of file diff --git a/justfile b/justfile index 5a4c15b..f40ed51 100644 --- a/justfile +++ b/justfile @@ -36,7 +36,7 @@ test: cargo test --all clippy: - cargo clippy --all + RUSTFLAGS="-D warnings" cargo clippy --all fmt: cargo +nightly fmt --all @@ -70,15 +70,18 @@ update-toc: generate-completions: ./bin/generate-completions +man-watch: + cargo build + cargo watch \ + --ignore '/man' \ + --ignore '/man/*' \ + --ignore '/book/src/commands' \ + --ignore '/book/src/commands/*' \ + --clear --exec 'run --package man' + man: cargo build - help2man \ - --name 'BitTorrent metainfo utility' \ - --manual 'IMDL MANUAL' \ - --no-info \ - target/debug/imdl \ - > man/imdl.1 - sd '📦 ' "\n" man/imdl.1 + cargo run --package man check-man: man git diff --no-ext-diff --quiet --exit-code diff --git a/man/imdl-completions.1 b/man/imdl-completions.1 new file mode 100644 index 0000000..d5e2929 --- /dev/null +++ b/man/imdl-completions.1 @@ -0,0 +1,19 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-COMPLETIONS "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ completions\fR +- Print shell completion scripts to standard output. +.SH "SYNOPSIS:" +.IP +imdl completions \fB\-\-shell\fR +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-s\fR, \fB\-\-shell\fR +Print completions for `SHELL`. [possible values: zsh, bash, fish, powershell, elvish] diff --git a/man/imdl-torrent-create.1 b/man/imdl-torrent-create.1 new file mode 100644 index 0000000..06a2963 --- /dev/null +++ b/man/imdl-torrent-create.1 @@ -0,0 +1,157 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-CREATE "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ create\fR +- Create a `.torrent` file. +.SH "SYNOPSIS:" +.IP +imdl torrent create [FLAGS] [OPTIONS] \fB\-\-input\fR +.SH "FLAGS:" +.TP +\fB\-n\fR, \fB\-\-dry\-run\fR +Skip writing `.torrent` file to disk. +.TP +\fB\-F\fR, \fB\-\-follow\-symlinks\fR +Follow symlinks in torrent input. By default, symlinks to files and directories are not +included in torrent contents. +.TP +\fB\-f\fR, \fB\-\-force\fR +Overwrite the destination `.torrent` file, if it exists. +.TP +\fB\-\-help\fR +Print help message. +.TP +\fB\-h\fR, \fB\-\-include\-hidden\fR +Include hidden files that would otherwise be skipped, such as files that start with a `.`, +and files hidden by file attributes on macOS and Windows. +.TP +\fB\-j\fR, \fB\-\-include\-junk\fR +Include junk files that would otherwise be skipped. +.TP +\fB\-M\fR, \fB\-\-md5\fR +Include MD5 checksum of each file in the torrent. N.B. MD5 is cryptographically broken and +only suitable for checking for accidental corruption. +.TP +\fB\-\-no\-created\-by\fR +Do not populate `created by` key of generated torrent with imdl version information. +.TP +\fB\-\-no\-creation\-date\fR +Do not populate `creation date` key of generated torrent with current time. +.TP +\fB\-O\fR, \fB\-\-open\fR +Open `.torrent` file after creation. Uses `xdg\-open`, `gnome\-open`, or `kde\-open` on +Linux; `open` on macOS; and `cmd \fI\,/C\/\fP start` on Windows +.TP +\fB\-\-link\fR +Print created torrent `magnet:` URL to standard output +.TP +\fB\-P\fR, \fB\-\-private\fR +Set the `private` flag. Torrent clients that understand the flag and participate in the +swarm of a torrent with the flag set will only announce themselves to the announce URLs +included in the torrent, and will not use other peer discovery mechanisms, such as the DHT +or local peer discovery. See BEP 27: Private Torrents for more information. +.TP +\fB\-S\fR, \fB\-\-show\fR +Display information about created torrent file. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-A\fR, \fB\-\-allow\fR ... +Allow `LINT`. Lints check for conditions which, although permitted, are not +usually desirable. For example, piece length can be any non\-zero value, but +probably shouldn't be below 16 KiB. The lint `small\-piece\-size` checks for +this, and `\-\-allow small\-piece\-size` can be used to disable this check. +[possible values: private\-trackerless, small\-piece\-length, uneven\-piece\-length] +.TP +\fB\-a\fR, \fB\-\-announce\fR +Use `URL` as the primary tracker announce URL. To supply multiple announce +URLs, also use `\-\-announce\-tier`. +.TP +\fB\-t\fR, \fB\-\-announce\-tier\fR ... +Use `URL\-LIST` as a tracker announce tier. Each instance adds a new tier. To +add multiple trackers to a given tier, separate their announce URLs with +commas: +.TP +`\-\-announce\-tier +udp://example.com:80/announce,https://example.net:443/announce` +.TP +Announce tiers are stored in the `announce\-list` key of the top\-level metainfo +dictionary as a list of lists of strings, as defined by BEP 12: Multitracker +Metadata Extension. +.TP +Note: Many BitTorrent clients do not implement the behavior described in BEP +12. See the discussion here for more details: +https://github.com/bittorrent/bittorrent.org/issues/82 +.TP +\fB\-c\fR, \fB\-\-comment\fR +Include `TEXT` as the comment for generated `.torrent` file. Stored under +`comment` key of top\-level metainfo dictionary. +.TP +\fB\-\-node\fR ... +Add DHT bootstrap node `NODE` to torrent. `NODE` should be in the form +`HOST:PORT`, where `HOST` is a domain name, an IPv4 address, or an IPv6 address +surrounded by brackets. May be given more than once to add multiple bootstrap +nodes. +.IP +Examples: +.IP +\fB\-\-node\fR router.example.com:1337 +.IP +\fB\-\-node\fR 203.0.113.0:2290 +.IP +\fB\-\-node\fR [2001:db8:4275:7920:6269:7463:6f69:6e21]:8832 +.TP +\fB\-g\fR, \fB\-\-glob\fR ... +Include or exclude files that match `GLOB`. Multiple glob may be provided, with +the last one taking precedence. Precede a glob with `!` to exclude it. +.TP +\fB\-i\fR, \fB\-\-input\fR +Read torrent contents from `PATH`. If `PATH` is a file, torrent will be a +single\-file torrent. If `PATH` is a directory, torrent will be a multi\-file +torrent. If `PATH` is `\-`, read from standard input. Piece length defaults to +256KiB when reading from standard input if `\-\-piece\-length` is not given. +.TP +\fB\-N\fR, \fB\-\-name\fR +Set name of torrent to `TEXT`. Defaults to the filename of the argument to +`\-\-input`. Required when `\-\-input \-`. +.TP +\fB\-o\fR, \fB\-\-output\fR +Save `.torrent` file to `TARGET`, or print to standard output if `TARGET` is +`\-`. Defaults to the argument to `\-\-input` with an `.torrent` extension +appended. Required when `\-\-input \-`. +.TP +\fB\-\-peer\fR ... +Add `PEER` to magnet link. +.TP +\fB\-p\fR, \fB\-\-piece\-length\fR +Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and gib. +.TP +\fB\-\-sort\-by\fR ... +Set the order of files within a torrent. `SPEC` should be of the form +`KEY:ORDER`, with `KEY` being one of `path` or `size`, and `ORDER` being +`ascending` or `descending`. `:ORDER` defaults to `ascending` if omitted. The +`\-\-sort\-by` flag may be given more than once, with later values being used to +break ties. Ties that remain are broken in ascending path order. +.IP +Sort in ascending order by path, the default: +.IP +\fB\-\-sort\-by\fR path:ascending +.IP +Sort in ascending order by path, more concisely: +.IP +\fB\-\-sort\-by\fR path +.IP +Sort in ascending order by size, break ties in descending path order: +.IP +\fB\-\-sort\-by\fR size:ascending \fB\-\-sort\-by\fR path:descending +.TP +\fB\-s\fR, \fB\-\-source\fR +Set torrent source to `TEXT`. Stored under `source` key of info dictionary. +This is useful for keeping statistics from being mis\-reported when +participating in swarms with the same contents, but with different trackers. +When source is set to a unique value for torrents with the same contents, +torrent clients will treat them as distinct torrents, and not share peers +between them, and will correctly report download and upload statistics to +multiple trackers. diff --git a/man/imdl-torrent-link.1 b/man/imdl-torrent-link.1 new file mode 100644 index 0000000..a31418d --- /dev/null +++ b/man/imdl-torrent-link.1 @@ -0,0 +1,27 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-LINK "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ link\fR +- Generate a magnet link from a `.torrent` file. +.SH "SYNOPSIS:" +.IP +imdl torrent link [FLAGS] [OPTIONS] \fB\-\-input\fR +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-O\fR, \fB\-\-open\fR +Open generated magnet link. Uses `xdg\-open`, `gnome\-open`, or `kde\-open` on Linux; `open` on macOS; +and `cmd \fI\,/C\/\fP start` on Windows +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-i\fR, \fB\-\-input\fR +Generate magnet link from metainfo at `PATH`. If `PATH` is `\-`, read metainfo from +standard input. +.TP +\fB\-p\fR, \fB\-\-peer\fR ... +Add `PEER` to magnet link. diff --git a/man/imdl-torrent-piece-length.1 b/man/imdl-torrent-piece-length.1 new file mode 100644 index 0000000..3e8ba32 --- /dev/null +++ b/man/imdl-torrent-piece-length.1 @@ -0,0 +1,15 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-PIECE-LENGTH "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ piece-length\fR +- Display information about automatic piece length selection. +.SH "SYNOPSIS:" +.IP +imdl torrent piece\-length +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. diff --git a/man/imdl-torrent-show.1 b/man/imdl-torrent-show.1 new file mode 100644 index 0000000..1d5ba51 --- /dev/null +++ b/man/imdl-torrent-show.1 @@ -0,0 +1,20 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-SHOW "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ show\fR +- Display information about a `.torrent` file. +.SH "SYNOPSIS:" +.IP +imdl torrent show \fB\-\-input\fR +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-i\fR, \fB\-\-input\fR +Show information about torrent at `PATH`. If `Path` is `\-`, read torrent metainfo from +standard input. diff --git a/man/imdl-torrent-stats.1 b/man/imdl-torrent-stats.1 new file mode 100644 index 0000000..24cb3b7 --- /dev/null +++ b/man/imdl-torrent-stats.1 @@ -0,0 +1,34 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-STATS "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ stats\fR +- Show statistics about a collection of `.torrent` files. +.SH "SYNOPSIS:" +.IP +imdl torrent stats [FLAGS] [OPTIONS] \fB\-\-input\fR +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-p\fR, \fB\-\-print\fR +Pretty print the contents of each torrent as it is processed. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-e\fR, \fB\-\-extract\-pattern\fR ... +Extract and display values under key paths that match `REGEX`. Subkeys of a +bencodeded dictionary are delimited by `/`, and values of a bencoded list are +delmited by `*`. For example, given the following bencoded dictionary `{"foo": +[{"bar": {"baz": 2}}]}`, the value `2`'s key path will be `foo*bar/baz`. The +value `2` would be displayed if any of `bar`, `foo[*]bar/baz`, or `foo.*baz` +were passed to `\-\-extract\-pattern. +.TP +\fB\-i\fR, \fB\-\-input\fR +Search `PATH` for torrents. May be a directory or a single torrent file. +.TP +\fB\-l\fR, \fB\-\-limit\fR +Stop after processing `N` torrents. Useful when processing large collections of +`.torrent` files. diff --git a/man/imdl-torrent-verify.1 b/man/imdl-torrent-verify.1 new file mode 100644 index 0000000..b433012 --- /dev/null +++ b/man/imdl-torrent-verify.1 @@ -0,0 +1,24 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT-VERIFY "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\ verify\fR +- Verify files against a `.torrent` file. +.SH "SYNOPSIS:" +.IP +imdl torrent verify [OPTIONS] \fB\-\-input\fR +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "OPTIONS:" +.TP +\fB\-c\fR, \fB\-\-content\fR +Verify torrent content at `PATH` against torrent metainfo. Defaults to `name` field of +torrent info dictionary. +.TP +\fB\-i\fR, \fB\-\-input\fR +Verify torrent contents against torrent metainfo in `METAINFO`. If `METAINFO` is `\-`, read +metainfo from standard input. diff --git a/man/imdl-torrent.1 b/man/imdl-torrent.1 new file mode 100644 index 0000000..c0b4217 --- /dev/null +++ b/man/imdl-torrent.1 @@ -0,0 +1,37 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. +.TH IMDL-TORRENT "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" +.SH NAME +\fBimdl\ torrent\fR +- Subcommands related to the BitTorrent protocol. +.SH "SYNOPSIS:" +.IP +imdl torrent +.SH "FLAGS:" +.TP +\fB\-h\fR, \fB\-\-help\fR +Print help message. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print version number. +.SH "SUBCOMMANDS:" +.TP +create +Create a `.torrent` file. +.TP +help +Prints this message or the help of the given subcommand(s) +.TP +link +Generate a magnet link from a `.torrent` file. +.TP +piece\-length +Display information about automatic piece length selection. +.TP +show +Display information about a `.torrent` file. +.TP +stats +Show statistics about a collection of `.torrent` files. +.TP +verify +Verify files against a `.torrent` file. diff --git a/man/imdl.1 b/man/imdl.1 index 2c448ae..982360d 100644 --- a/man/imdl.1 +++ b/man/imdl.1 @@ -1,32 +1,31 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.47.11. -.TH IMDL "1" "April 2020" "imdl v0.1.2" "IMDL MANUAL" +.TH \FBIMDL\FR "1" "April 2020" "Intermodal v0.1.2" "Intermodal Manual" .SH NAME -imdl \- BitTorrent metainfo utility -.SH DESCRIPTION -imdl v0.1.2 -Casey Rodarmor - -A 40' shipping container for the internet \- https://github.com/casey/intermodal -.SS "USAGE:" +\fBimdl\fR +- A 40' shipping container for the Internet +.SH "SYNOPSIS:" .IP imdl [FLAGS] [OPTIONS] -.SS "FLAGS:" +.SH "FLAGS:" .TP \fB\-h\fR, \fB\-\-help\fR Print help message. .TP \fB\-u\fR, \fB\-\-unstable\fR -Enable unstable features. To avoid premature stabilization and excessive version churn, unstable features are unavailable unless this flag is set. Unstable features are not bound by -semantic versioning stability guarantees, and may be changed or removed at any time. +Enable unstable features. To avoid premature stabilization and excessive version churn, unstable +features are unavailable unless this flag is set. Unstable features are not bound by semantic +versioning stability guarantees, and may be changed or removed at any time. .TP \fB\-V\fR, \fB\-\-version\fR Print version number. -.SS "OPTIONS:" +.SH "OPTIONS:" .TP \fB\-\-color\fR -Print colorful output according to `WHEN`. When `auto`, the default, colored output is only enabled if imdl detects that it is connected to a terminal, the `NO_COLOR` environment -variable is not set, and the `TERM` environment variable is not set to `dumb`. [default: auto] [possible values: auto, always, never] -.SS "SUBCOMMANDS:" +Print colorful output according to `WHEN`. When `auto`, the default, colored output is only +enabled if imdl detects that it is connected to a terminal, the `NO_COLOR` environment +variable is not set, and the `TERM` environment variable is not set to `dumb`. [default: auto] +[possible values: auto, always, never] +.SH "SUBCOMMANDS:" .TP completions Print shell completion scripts to standard output.