Skip to content

Commit

Permalink
Render command help text in book to avoid wrapping
Browse files Browse the repository at this point in the history 
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: #364
  • Loading branch information
@casey
casey committed Apr 11, 2020
1 parent ed34ff4 commit f058072
Show file tree
Hide file tree
Showing 11 changed files with 201 additions and 127 deletions.
3 changes: 2 additions & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>_
Expand Down
17 changes: 12 additions & 5 deletions bin/man/src/subcommand.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,17 +32,18 @@ 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()?;

const MARKER: &str = "\nSUBCOMMANDS:\n";

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();
Expand All @@ -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!(
Expand Down Expand Up @@ -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,
}
Expand Down
3 changes: 2 additions & 1 deletion book/src/commands/imdl-completions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
```
209 changes: 121 additions & 88 deletions book/src/commands/imdl-torrent-create.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,99 +8,132 @@ 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:
`--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 -`.
-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.
-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.
```
9 changes: 5 additions & 4 deletions book/src/commands/imdl-torrent-link.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 2 additions & 2 deletions book/src/commands/imdl-torrent-show.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
```
Loading

0 comments on commit f058072

Please sign in to comment.