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
-----------------------
- :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: [`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>_

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

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

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

@ -11,6 +11,7 @@ FLAGS:
-V, --version Print version number.
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]
```

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

@ -8,55 +8,75 @@ USAGE:
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.
-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.
-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:
-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.
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:
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.
-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:
@ -65,24 +85,34 @@ OPTIONS:
--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 -`.
-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.
-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:
@ -92,15 +122,18 @@ OPTIONS:
--sort-by path
Sort in ascending order by size, break ties in descending path order:
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.
-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.
```

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

@ -8,13 +8,14 @@ USAGE:
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
-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.
-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.
```

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

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

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

@ -8,18 +8,24 @@ USAGE:
FLAGS:
-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.
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.
-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.
```

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

@ -11,9 +11,11 @@ FLAGS:
-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.
-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.
```

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

@ -12,9 +12,11 @@ FLAGS:
SUBCOMMANDS:
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.
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.
stats Show statistics about a collection of `.torrent` files.
verify Verify files against a `.torrent` file.

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

@ -2,27 +2,34 @@
```
imdl v0.1.4
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:
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.
-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]
--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)
help Prints this message or the help of the given
subcommand(s)
torrent Subcommands related to the BitTorrent protocol.
```

16
src/env.rs
View File

@ -36,7 +36,21 @@ impl Env {
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;
self.err.set_use_color(use_color);