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.