programmer/intermodal
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add bin/man command for generating man pages

Browse Source 
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
This commit is contained in:
Casey Rodarmor 2020-04-08 12:19:50 -07:00
parent 14fff1d888
commit 268c62b66d
No known key found for this signature in database
GPG Key ID: 556186B153EC6FE0
30 changed files with 933 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CHANGELOG.md
View File

@ -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 <casey@rodarmor.com>_
- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Add `bin/man` command for generating man pages - _Casey Rodarmor <casey@rodarmor.com>_
- :books: [`14fff1d888a3`](https://github.com/casey/intermodal/commit/14fff1d888a3d4aebd88059feacde5c665019f30) Make smaller demo for readme - _Casey Rodarmor <casey@rodarmor.com>_
- :books: [`4f8b6a212e80`](https://github.com/casey/intermodal/commit/4f8b6a212e8099ebfcf14600ce92863583758231) Improve demo GIF - _Casey Rodarmor <casey@rodarmor.com>_

10
Cargo.lock generated
View File

@ -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"

3
Cargo.toml
View File

@ -70,4 +70,7 @@ members = [
# generate the changelog from git commits
"bin/changelog",
# generate man page
"bin/man"
]

12
bin/man/Cargo.toml Normal file
View File

@ -0,0 +1,12 @@
[package]
name = "man"
version = "0.0.0"
authors = ["Casey Rodarmor <casey@rodarmor.com>"]
edition = "2018"
publish = false
[dependencies]
anyhow = "1.0.28"
fehler = "1.0.0"
tempfile = "3.1.0"
regex = "1.3.6"

38
bin/man/src/bin.rs Normal file
View File

@ -0,0 +1,38 @@
use crate::common::*;
#[derive(Debug)]
pub(crate) struct Bin {
pub(crate) bin: String,
pub(crate) subcommands: Vec<Subcommand>,
}
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<String>) {
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);
}
}

12
bin/man/src/common.rs Normal file
View File

@ -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};

57
bin/man/src/main.rs Normal file
View File

@ -0,0 +1,57 @@
use crate::common::*;
mod bin;
mod common;
mod subcommand;
#[throws]
fn clean(dir: impl AsRef<Path>) {
let dir = dir.as_ref();
fs::remove_dir_all(dir)?;
fs::create_dir_all(dir)?;
}
#[throws]
fn write(dst: impl AsRef<Path>, 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)?;
}

149
bin/man/src/subcommand.rs Normal file
View File

@ -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<String>,
pub(crate) help: String,
pub(crate) man: String,
pub(crate) subcommands: Vec<String>,
}
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<String>) -> 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)
}
}

16
book/book.toml
View File

@ -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"

11
book/src/SUMMARY.md
View File

@ -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)

4
book/src/commands.md Normal file
View File

@ -0,0 +1,4 @@
Commands
========
This page intentionally left blank.

16
book/src/commands/imdl-completions.md Normal file
View File

@ -0,0 +1,16 @@
# `imdl completions`
```
imdl-completions 0.1.2
Print shell completion scripts to standard output.
USAGE:
imdl completions --shell <SHELL>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-s, --shell <SHELL> Print completions for `SHELL`. [possible values: zsh, bash, fish, powershell, elvish]
```

106
book/src/commands/imdl-torrent-create.md Normal file
View File

@ -0,0 +1,106 @@
# `imdl torrent create`
```
imdl-torrent-create 0.1.2
Create a `.torrent` file.
USAGE:
imdl torrent create [FLAGS] [OPTIONS] --input <PATH>
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 <LINT>... 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 <URL> Use `URL` as the primary tracker announce URL. To supply multiple announce
URLs, also use `--announce-tier`.
-t, --announce-tier <URL-LIST>... 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 <TEXT> Include `TEXT` as the comment for generated `.torrent` file. Stored under
`comment` key of top-level metainfo dictionary.
--node <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 <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 <PATH> 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 <TEXT> Set name of torrent to `TEXT`. Defaults to the filename of the argument to
`--input`. Required when `--input -`.
-o, --output <TARGET> 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 <PEER>... Add `PEER` to magnet link.
-p, --piece-length <BYTES> Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and gib.
--sort-by <SPEC>... 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 <TEXT> 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.
```

20
book/src/commands/imdl-torrent-link.md Normal file
View File

@ -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 <METAINFO>
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 <METAINFO> Generate magnet link from metainfo at `PATH`. If `PATH` is `-`, read metainfo from
standard input.
-p, --peer <PEER>... Add `PEER` to magnet link.
```

13
book/src/commands/imdl-torrent-piece-length.md Normal file
View File

@ -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.
```

17
book/src/commands/imdl-torrent-show.md Normal file
View File

@ -0,0 +1,17 @@
# `imdl torrent show`
```
imdl-torrent-show 0.1.2
Display information about a `.torrent` file.
USAGE:
imdl torrent show --input <PATH>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-i, --input <PATH> Show information about torrent at `PATH`. If `Path` is `-`, read torrent metainfo from
standard input.
```

25
book/src/commands/imdl-torrent-stats.md Normal file
View File

@ -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 <PATH>
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 <REGEX>... 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 <PATH> Search `PATH` for torrents. May be a directory or a single torrent file.
-l, --limit <N> Stop after processing `N` torrents. Useful when processing large collections of
`.torrent` files.
```

19
book/src/commands/imdl-torrent-verify.md Normal file
View File

@ -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 <METAINFO>
FLAGS:
-h, --help Print help message.
-V, --version Print version number.
OPTIONS:
-c, --content <PATH> Verify torrent content at `PATH` against torrent metainfo. Defaults to `name` field of
torrent info dictionary.
-i, --input <METAINFO> Verify torrent contents against torrent metainfo in `METAINFO`. If `METAINFO` is `-`, read
metainfo from standard input.
```

22
book/src/commands/imdl-torrent.md Normal file
View File

@ -0,0 +1,22 @@
# `imdl torrent`
```
imdl-torrent 0.1.2
Subcommands related to the BitTorrent protocol.
USAGE:
imdl torrent <SUBCOMMAND>
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.
```

28
book/src/commands/imdl.md Normal file
View File

@ -0,0 +1,28 @@
# `imdl`
```
imdl v0.1.2
Casey Rodarmor <casey@rodarmor.com>
📦 A 40' shipping container for the internet - https://github.com/casey/intermodal
USAGE:
imdl [FLAGS] [OPTIONS] <SUBCOMMAND>
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 <WHEN> 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.
```

19
justfile
View File

@ -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

19
man/imdl-completions.1 Normal file
View File

@ -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 <SHELL>
.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 <SHELL>
Print completions for `SHELL`. [possible values: zsh, bash, fish, powershell, elvish]

157
man/imdl-torrent-create.1 Normal file
View File

@ -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 <PATH>
.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 <LINT>...
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 <URL>
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 <URL\-LIST>...
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 <TEXT>
Include `TEXT` as the comment for generated `.torrent` file. Stored under
`comment` key of top\-level metainfo dictionary.
.TP
\fB\-\-node\fR <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.
.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 <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.
.TP
\fB\-i\fR, \fB\-\-input\fR <PATH>
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 <TEXT>
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 <TARGET>
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 <PEER>...
Add `PEER` to magnet link.
.TP
\fB\-p\fR, \fB\-\-piece\-length\fR <BYTES>
Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and gib.
.TP
\fB\-\-sort\-by\fR <SPEC>...
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 <TEXT>
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.

27
man/imdl-torrent-link.1 Normal file
View File

@ -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 <METAINFO>
.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 <METAINFO>
Generate magnet link from metainfo at `PATH`. If `PATH` is `\-`, read metainfo from
standard input.
.TP
\fB\-p\fR, \fB\-\-peer\fR <PEER>...
Add `PEER` to magnet link.

15
man/imdl-torrent-piece-length.1 Normal file
View File

@ -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.

20
man/imdl-torrent-show.1 Normal file
View File

@ -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 <PATH>
.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 <PATH>
Show information about torrent at `PATH`. If `Path` is `\-`, read torrent metainfo from
standard input.

34
man/imdl-torrent-stats.1 Normal file
View File

@ -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 <PATH>
.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 <REGEX>...
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 <PATH>
Search `PATH` for torrents. May be a directory or a single torrent file.
.TP
\fB\-l\fR, \fB\-\-limit\fR <N>
Stop after processing `N` torrents. Useful when processing large collections of
`.torrent` files.

24
man/imdl-torrent-verify.1 Normal file
View File

@ -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 <METAINFO>
.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 <PATH>
Verify torrent content at `PATH` against torrent metainfo. Defaults to `name` field of
torrent info dictionary.
.TP
\fB\-i\fR, \fB\-\-input\fR <METAINFO>
Verify torrent contents against torrent metainfo in `METAINFO`. If `METAINFO` is `\-`, read
metainfo from standard input.

37
man/imdl-torrent.1 Normal file
View File

@ -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 <SUBCOMMAND>
.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.

29
man/imdl.1
View File

@ -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 <casey@rodarmor.com>
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] <SUBCOMMAND>
.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 <WHEN>
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.