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

Render command help text in book to avoid wrapping

Browse Source 
The command `--help` text output in the book was very wide, which caused
it to be clipped and require scrolling horizontally to see it all.

This diff renders the text at 80 columns, which makes it visible without
scrolling at reasonable screen sizes.

To do this, `env::run` now checks for the presence of the environment
variable `IMDL_TERM_WIDTH`, which, if set to a positive integer, will be
passed to `Clap::set_term_width`.

`bin/man` now uses this to render the help text at 80 characters.

type: documentation
pr: https://github.com/casey/intermodal/pull/364
This commit is contained in:
Casey Rodarmor 2020-04-11 03:54:20 -07:00
parent ed34ff48a7
commit f05807290b
No known key found for this signature in database
GPG Key ID: 556186B153EC6FE0
11 changed files with 201 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -4,7 +4,8 @@ Changelog
UNRELEASED - 2020-04-11 UNRELEASED - 2020-04-11
----------------------- -----------------------
- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Add `fuchsi/maketorrent` to prior art table - _Casey Rodarmor <casey@rodarmor.com>_ - :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Render command help text in book to avoid wrapping ([#364](https://github.com/casey/intermodal/pull/364)) - _Casey Rodarmor <casey@rodarmor.com>_
- :books: [`ed34ff48a740`](https://github.com/casey/intermodal/commit/ed34ff48a7406adb8b4cdb523b5dc1bf9435e1bc) Add `fuchsi/maketorrent` to prior art table ([#362](https://github.com/casey/intermodal/pull/362)) - _Casey Rodarmor <casey@rodarmor.com>_
- :books: [`a3f46187229f`](https://github.com/casey/intermodal/commit/a3f46187229f499e7a13ec5ce656408ba95d1dcc) Rename distributing large datasets ([#361](https://github.com/casey/intermodal/pull/361)) - _Casey Rodarmor <casey@rodarmor.com>_ - :books: [`a3f46187229f`](https://github.com/casey/intermodal/commit/a3f46187229f499e7a13ec5ce656408ba95d1dcc) Rename distributing large datasets ([#361](https://github.com/casey/intermodal/pull/361)) - _Casey Rodarmor <casey@rodarmor.com>_
- :books: [`1c9ff0cde491`](https://github.com/casey/intermodal/commit/1c9ff0cde4910f369e75930257ce92a8cf4c6cd5) Add suggestions for distributing large datasets to book ([#360](https://github.com/casey/intermodal/pull/360)) - _Casey Rodarmor <casey@rodarmor.com>_ - :books: [`1c9ff0cde491`](https://github.com/casey/intermodal/commit/1c9ff0cde4910f369e75930257ce92a8cf4c6cd5) Add suggestions for distributing large datasets to book ([#360](https://github.com/casey/intermodal/pull/360)) - _Casey Rodarmor <casey@rodarmor.com>_
- :white_check_mark: [`ff6f6d4c3de1`](https://github.com/casey/intermodal/commit/ff6f6d4c3de1a14c6b2ebef270c0ec542300f0de) Test that `--glob`s match entire file paths ([#357](https://github.com/casey/intermodal/pull/357)) - _Casey Rodarmor <casey@rodarmor.com>_ - :white_check_mark: [`ff6f6d4c3de1`](https://github.com/casey/intermodal/commit/ff6f6d4c3de1a14c6b2ebef270c0ec542300f0de) Test that `--glob`s match entire file paths ([#357](https://github.com/casey/intermodal/pull/357)) - _Casey Rodarmor <casey@rodarmor.com>_

17
bin/man/src/subcommand.rs
View File

@ -32,8 +32,9 @@ impl CommandExt for Command {
impl Subcommand { impl Subcommand {
#[throws] #[throws]
pub(crate) fn new(bin: &str, command: Vec<String>) -> Self { pub(crate) fn new(bin: &str, command: Vec<String>) -> Self {
let help = Command::new(bin) let wide_help = Command::new(bin)
.args(command.as_slice()) .args(command.as_slice())
.env("IMDL_TERM_WIDTH", "200")
.arg("--help") .arg("--help")
.out()?; .out()?;
@ -41,8 +42,8 @@ impl Subcommand {
let mut subcommands = Vec::new(); let mut subcommands = Vec::new();
if let Some(marker) = help.find(MARKER) { if let Some(marker) = wide_help.find(MARKER) {
let block = &help[marker + MARKER.len()..]; let block = &wide_help[marker + MARKER.len()..];
for line in block.lines() { for line in block.lines() {
let name = line.trim().split_whitespace().next().unwrap(); let name = line.trim().split_whitespace().next().unwrap();
@ -62,7 +63,7 @@ impl Subcommand {
let description = if command.is_empty() { let description = if command.is_empty() {
"A 40' shipping container for the Internet".to_string() "A 40' shipping container for the Internet".to_string()
} else { } else {
help.lines().nth(1).unwrap().into() wide_help.lines().nth(1).unwrap().into()
}; };
let include = format!( let include = format!(
@ -119,10 +120,16 @@ impl Subcommand {
let man = re.replace(&man, ".SH").into_owned(); let man = re.replace(&man, ".SH").into_owned();
let narrow_help = Command::new(bin)
.args(command.as_slice())
.env("IMDL_TERM_WIDTH", "80")
.arg("--help")
.out()?;
Self { Self {
bin: bin.into(), bin: bin.into(),
help: narrow_help,
command, command,
help,
man, man,
subcommands, subcommands,
} }

3
book/src/commands/imdl-completions.md
View File

@ -11,6 +11,7 @@ FLAGS:
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-s, --shell <SHELL> Print completions for `SHELL`. [possible values: zsh, bash, fish, powershell, elvish] -s, --shell <SHELL> Print completions for `SHELL`. [possible values: zsh,
bash, fish, powershell, elvish]
``` ```

209
book/src/commands/imdl-torrent-create.md
View File

@ -8,99 +8,132 @@ USAGE:
FLAGS: FLAGS:
-n, --dry-run Skip writing `.torrent` file to disk. -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 -F, --follow-symlinks Follow symlinks in torrent input. By default,
included in torrent contents. symlinks to files and directories are not included
-f, --force Overwrite the destination `.torrent` file, if it exists. in torrent contents.
-f, --force Overwrite the destination `.torrent` file, if it
exists.
--help Print help message. --help Print help message.
-h, --include-hidden Include hidden files that would otherwise be skipped, such as files that start with a `.`, -h, --include-hidden Include hidden files that would otherwise be
and files hidden by file attributes on macOS and Windows. skipped, such as files that start with a `.`, and
-j, --include-junk Include junk files that would otherwise be skipped. files hidden by file attributes on macOS and
-M, --md5 Include MD5 checksum of each file in the torrent. N.B. MD5 is cryptographically broken and Windows.
only suitable for checking for accidental corruption. -j, --include-junk Include junk files that would otherwise be
--no-created-by Do not populate `created by` key of generated torrent with imdl version information. skipped.
--no-creation-date Do not populate `creation date` key of generated torrent with current time. -M, --md5 Include MD5 checksum of each file in the torrent.
-O, --open Open `.torrent` file after creation. Uses `xdg-open`, `gnome-open`, or `kde-open` on N.B. MD5 is cryptographically broken and only
Linux; `open` on macOS; and `cmd /C start` on Windows suitable for checking for accidental corruption.
--link Print created torrent `magnet:` URL to standard output --no-created-by Do not populate `created by` key of generated
-P, --private Set the `private` flag. Torrent clients that understand the flag and participate in the torrent with imdl version information.
swarm of a torrent with the flag set will only announce themselves to the announce URLs --no-creation-date Do not populate `creation date` key of generated
included in the torrent, and will not use other peer discovery mechanisms, such as the DHT torrent with current time.
or local peer discovery. See BEP 27: Private Torrents for more information. -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. -S, --show Display information about created torrent file.
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-A, --allow <LINT>... Allow `LINT`. Lints check for conditions which, although permitted, are not -A, --allow <LINT>...
usually desirable. For example, piece length can be any non-zero value, but Allow `LINT`. Lints check for conditions which, although permitted,
probably shouldn't be below 16 KiB. The lint `small-piece-size` checks for are not usually desirable. For example, piece length can be any non-
this, and `--allow small-piece-size` can be used to disable this check. zero value, but probably shouldn't be below 16 KiB. The lint
[possible values: private-trackerless, small-piece-length, uneven-piece-length] `small-piece-size` checks for this, and `--allow small-piece-size`
-a, --announce <URL> Use `URL` as the primary tracker announce URL. To supply multiple announce can be used to disable this check. [possible values: private-
URLs, also use `--announce-tier`. trackerless, small-piece-length, uneven-piece-length]
-t, --announce-tier <URL-LIST>... Use `URL-LIST` as a tracker announce tier. Each instance adds a new tier. To -a, --announce <URL>
add multiple trackers to a given tier, separate their announce URLs with Use `URL` as the primary tracker announce URL. To supply multiple
commas: announce URLs, also use `--announce-tier`.
-t, --announce-tier <URL-LIST>...
`--announce-tier Use `URL-LIST` as a tracker announce tier. Each instance adds a new
udp://example.com:80/announce,https://example.net:443/announce` tier. To add multiple trackers to a given tier, separate their
announce URLs with commas:
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 `--announce-tier
Metadata Extension. udp://example.com:80/announce,https://example.net:443/announce`
Note: Many BitTorrent clients do not implement the behavior described in BEP Announce tiers are stored in the `announce-list` key of the top-
12. See the discussion here for more details: level metainfo dictionary as a list of lists of strings, as
https://github.com/bittorrent/bittorrent.org/issues/82 defined by BEP 12: Multitracker Metadata Extension.
-c, --comment <TEXT> Include `TEXT` as the comment for generated `.torrent` file. Stored under
`comment` key of top-level metainfo dictionary. Note: Many BitTorrent clients do not implement the behavior
--node <NODE>... Add DHT bootstrap node `NODE` to torrent. `NODE` should be in the form described in BEP 12. See the discussion here for more details:
`HOST:PORT`, where `HOST` is a domain name, an IPv4 address, or an IPv6 address https://github.com/bittorrent/bittorrent.org/issues/82
surrounded by brackets. May be given more than once to add multiple bootstrap -c, --comment <TEXT>
nodes. Include `TEXT` as the comment for generated `.torrent` file. Stored
under `comment` key of top-level metainfo dictionary.
Examples: --node <NODE>...
Add DHT bootstrap node `NODE` to torrent. `NODE` should be in the
--node router.example.com:1337 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
--node 203.0.113.0:2290 to add multiple bootstrap nodes.
--node [2001:db8:4275:7920:6269:7463:6f69:6e21]:8832 Examples:
-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. --node router.example.com:1337
-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 --node 203.0.113.0:2290
torrent. If `PATH` is `-`, read from standard input. Piece length defaults to
256KiB when reading from standard input if `--piece-length` is not given. --node [2001:db8:4275:7920:6269:7463:6f69:6e21]:8832
-N, --name <TEXT> Set name of torrent to `TEXT`. Defaults to the filename of the argument to -g, --glob <GLOB>...
`--input`. Required when `--input -`. Include or exclude files that match `GLOB`. Multiple glob may be
-o, --output <TARGET> Save `.torrent` file to `TARGET`, or print to standard output if `TARGET` is provided, with the last one taking precedence. Precede a glob with
`-`. Defaults to the argument to `--input` with an `.torrent` extension `!` to exclude it.
appended. Required when `--input -`. -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. --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. -p, --piece-length <BYTES>
--sort-by <SPEC>... Set the order of files within a torrent. `SPEC` should be of the form Set piece length to `BYTES`. Accepts SI units, e.g. kib, mib, and
`KEY:ORDER`, with `KEY` being one of `path` or `size`, and `ORDER` being gib.
`ascending` or `descending`. `:ORDER` defaults to `ascending` if omitted. The --sort-by <SPEC>...
`--sort-by` flag may be given more than once, with later values being used to Set the order of files within a torrent. `SPEC` should be of the
break ties. Ties that remain are broken in ascending path order. form `KEY:ORDER`, with `KEY` being one of `path` or `size`, and
`ORDER` being `ascending` or `descending`. `:ORDER` defaults to
Sort in ascending order by path, the default: `ascending` if omitted. The `--sort-by` flag may be given more than
once, with later values being used to break ties. Ties that remain
--sort-by path:ascending are broken in ascending path order.
Sort in ascending order by path, more concisely: Sort in ascending order by path, the default:
--sort-by path --sort-by path:ascending
Sort in ascending order by size, break ties in descending path order: Sort in ascending order by path, more concisely:
--sort-by size:ascending --sort-by path:descending --sort-by path
-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 Sort in ascending order by size, break ties in descending path
participating in swarms with the same contents, but with different trackers. order:
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 --sort-by size:ascending --sort-by path:descending
between them, and will correctly report download and upload statistics to -s, --source <TEXT>
multiple trackers. 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.
``` ```

9
book/src/commands/imdl-torrent-link.md
View File

@ -8,13 +8,14 @@ USAGE:
FLAGS: FLAGS:
-h, --help Print help message. -h, --help Print help message.
-O, --open Open generated magnet link. Uses `xdg-open`, `gnome-open`, or `kde-open` on Linux; `open` on macOS; -O, --open Open generated magnet link. Uses `xdg-open`, `gnome-open`,
and `cmd /C start` on Windows or `kde-open` on Linux; `open` on macOS; and `cmd /C start`
on Windows
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-i, --input <METAINFO> Generate magnet link from metainfo at `PATH`. If `PATH` is `-`, read metainfo from -i, --input <METAINFO> Generate magnet link from metainfo at `PATH`. If
standard input. `PATH` is `-`, read metainfo from standard input.
-p, --peer <PEER>... Add `PEER` to magnet link. -p, --peer <PEER>... Add `PEER` to magnet link.
``` ```

4
book/src/commands/imdl-torrent-show.md
View File

@ -11,7 +11,7 @@ FLAGS:
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-i, --input <PATH> Show information about torrent at `PATH`. If `Path` is `-`, read torrent metainfo from -i, --input <PATH> Show information about torrent at `PATH`. If `Path` is
standard input. `-`, read torrent metainfo from standard input.
``` ```

26
book/src/commands/imdl-torrent-stats.md
View File

@ -8,18 +8,24 @@ USAGE:
FLAGS: FLAGS:
-h, --help Print help message. -h, --help Print help message.
-p, --print Pretty print the contents of each torrent as it is processed. -p, --print Pretty print the contents of each torrent as it is
processed.
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-e, --extract-pattern <REGEX>... Extract and display values under key paths that match `REGEX`. Subkeys of a -e, --extract-pattern <REGEX>...
bencodeded dictionary are delimited by `/`, and values of a bencoded list are Extract and display values under key paths that match `REGEX`.
delmited by `*`. For example, given the following bencoded dictionary `{"foo": Subkeys of a bencodeded dictionary are delimited by `/`, and values
[{"bar": {"baz": 2}}]}`, the value `2`'s key path will be `foo*bar/baz`. The of a bencoded list are delmited by `*`. For example, given the
value `2` would be displayed if any of `bar`, `foo[*]bar/baz`, or `foo.*baz` following bencoded dictionary `{"foo": [{"bar": {"baz": 2}}]}`, the
were passed to `--extract-pattern. value `2`'s key path will be `foo*bar/baz`. The value `2` would be
-i, --input <PATH> Search `PATH` for torrents. May be a directory or a single torrent file. displayed if any of `bar`, `foo[*]bar/baz`, or `foo.*baz` were
-l, --limit <N> Stop after processing `N` torrents. Useful when processing large collections of passed to `--extract-pattern.
`.torrent` files. -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.
``` ```

10
book/src/commands/imdl-torrent-verify.md
View File

@ -11,9 +11,11 @@ FLAGS:
-V, --version Print version number. -V, --version Print version number.
OPTIONS: OPTIONS:
-c, --content <PATH> Verify torrent content at `PATH` against torrent metainfo. Defaults to `name` field of -c, --content <PATH> Verify torrent content at `PATH` against torrent
torrent info dictionary. metainfo. Defaults to `name` field of torrent info
-i, --input <METAINFO> Verify torrent contents against torrent metainfo in `METAINFO`. If `METAINFO` is `-`, read dictionary.
metainfo from standard input. -i, --input <METAINFO> Verify torrent contents against torrent metainfo
in `METAINFO`. If `METAINFO` is `-`, read metainfo
from standard input.
``` ```

6
book/src/commands/imdl-torrent.md
View File

@ -12,9 +12,11 @@ FLAGS:
SUBCOMMANDS: SUBCOMMANDS:
create Create a `.torrent` file. create Create a `.torrent` file.
help Prints this message or the help of the given subcommand(s) help Prints this message or the help of the given
subcommand(s)
link Generate a magnet link from a `.torrent` file. link Generate a magnet link from a `.torrent` file.
piece-length Display information about automatic piece length selection. piece-length Display information about automatic piece length
selection.
show Display information about a `.torrent` file. show Display information about a `.torrent` file.
stats Show statistics about a collection of `.torrent` files. stats Show statistics about a collection of `.torrent` files.
verify Verify files against a `.torrent` file. verify Verify files against a `.torrent` file.

25
book/src/commands/imdl.md
View File

@ -2,27 +2,34 @@
``` ```
imdl v0.1.4 imdl v0.1.4
Casey Rodarmor <casey@rodarmor.com> Casey Rodarmor <casey@rodarmor.com>
📦 A 40' shipping container for the internet - https://github.com/casey/intermodal 📦 A 40' shipping container for the internet -
https://github.com/casey/intermodal
USAGE: USAGE:
imdl [FLAGS] [OPTIONS] <SUBCOMMAND> imdl [FLAGS] [OPTIONS] <SUBCOMMAND>
FLAGS: FLAGS:
-h, --help Print help message. -h, --help Print help message.
-u, --unstable Enable unstable features. To avoid premature stabilization and excessive version churn, unstable -u, --unstable Enable unstable features. To avoid premature stabilization
features are unavailable unless this flag is set. Unstable features are not bound by semantic and excessive version churn, unstable features are
versioning stability guarantees, and may be changed or removed at any time. 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. -V, --version Print version number.
OPTIONS: OPTIONS:
--color <WHEN> Print colorful output according to `WHEN`. When `auto`, the default, colored output is only --color <WHEN> Print colorful output according to `WHEN`. When
enabled if imdl detects that it is connected to a terminal, the `NO_COLOR` environment `auto`, the default, colored output is only enabled if
variable is not set, and the `TERM` environment variable is not set to `dumb`. [default: auto] imdl detects that it is connected to a terminal, the
[possible values: auto, always, never] `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: SUBCOMMANDS:
completions Print shell completion scripts to standard output. completions Print shell completion scripts to standard output.
help Prints this message or the help of the given subcommand(s) help Prints this message or the help of the given
subcommand(s)
torrent Subcommands related to the BitTorrent protocol. torrent Subcommands related to the BitTorrent protocol.
``` ```

16
src/env.rs
View File

@ -36,7 +36,21 @@ impl Env {
Self::initialize_logging(); Self::initialize_logging();
let args = Arguments::from_iter_safe(&self.args)?; let app = Arguments::clap();
let width = env::var("IMDL_TERM_WIDTH")
.ok()
.and_then(|width| width.parse::<usize>().ok());
let app = if let Some(width) = width {
app.set_term_width(width)
} else {
app
};
let matches = app.get_matches_from_safe(&self.args)?;
let args = Arguments::from_clap(&matches);
let use_color = args.options().use_color; let use_color = args.options().use_color;
self.err.set_use_color(use_color); self.err.set_use_color(use_color);