Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update manpage formatting #9136

Merged
merged 5 commits into from Nov 16, 2020
Merged

Update manpage formatting #9136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eb16624
manpage: reformat lists of subcommands & env vars
EricFromCanada Nov 11, 2020
19f3ace
manpage: update instructions & description in template file
EricFromCanada Nov 12, 2020
f784b71
manpage: fixes for grammar
EricFromCanada Nov 12, 2020
72bc057
manpage: fixes for formatting
EricFromCanada Nov 12, 2020
c1ff5ef
docs/vale-styles/Homebrew/Titles: fix Linux reference.
MikeMcQuaid Nov 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 0 additions & 1 deletion Library/Homebrew/cask/cmd.rb
View file
Open in desktop
Expand Up @@ -78,7 +78,6 @@ def self.description

Commands:
#{command_lines.join}

See also: `man brew`
EOS
end
Expand Down
4 changes: 2 additions & 2 deletions Library/Homebrew/cask/cmd/abstract_command.rb
View file
Open in desktop
Expand Up @@ -42,15 +42,15 @@ def self.banner_headline

OPTIONS = [
[:switch, "--[no-]binaries", {
description: "Disable/enable linking of helper executables. Default: enabled",
description: "Disable/enable linking of helper executables (default: enabled).",
env: :cask_opts_binaries,
}],
[:switch, "--require-sha", {
description: "Require all casks to have a checksum.",
env: :cask_opts_require_sha,
}],
[:switch, "--[no-]quarantine", {
description: "Disable/enable quarantining of downloads. Default: enabled",
description: "Disable/enable quarantining of downloads (default: enabled).",
env: :cask_opts_quarantine,
}],
].freeze
Expand Down
64 changes: 32 additions & 32 deletions Library/Homebrew/cli/parser.rb
View file
Open in desktop
Expand Up @@ -33,65 +33,65 @@ def self.from_cmd_path(cmd_path)
def self.global_cask_options
[
[:flag, "--appdir=", {
description: "Target location for Applications. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:appdir]}`",
description: "Target location for Applications " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:appdir]}`).",
}],
[:flag, "--colorpickerdir=", {
description: "Target location for Color Pickers. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:colorpickerdir]}`",
description: "Target location for Color Pickers " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:colorpickerdir]}`).",
}],
[:flag, "--prefpanedir=", {
description: "Target location for Preference Panes. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:prefpanedir]}`",
description: "Target location for Preference Panes " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:prefpanedir]}`).",
}],
[:flag, "--qlplugindir=", {
description: "Target location for QuickLook Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:qlplugindir]}`",
description: "Target location for QuickLook Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:qlplugindir]}`).",
}],
[:flag, "--mdimporterdir=", {
description: "Target location for Spotlight Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:mdimporterdir]}`",
description: "Target location for Spotlight Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:mdimporterdir]}`).",
}],
[:flag, "--dictionarydir=", {
description: "Target location for Dictionaries. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:dictionarydir]}`",
description: "Target location for Dictionaries " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:dictionarydir]}`).",
}],
[:flag, "--fontdir=", {
description: "Target location for Fonts. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:fontdir]}`",
description: "Target location for Fonts " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:fontdir]}`).",
}],
[:flag, "--servicedir=", {
description: "Target location for Services. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:servicedir]}`",
description: "Target location for Services " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:servicedir]}`).",
}],
[:flag, "--input_methoddir=", {
description: "Target location for Input Methods. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:input_methoddir]}`",
description: "Target location for Input Methods " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:input_methoddir]}`).",
}],
[:flag, "--internet_plugindir=", {
description: "Target location for Internet Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:internet_plugindir]}`",
description: "Target location for Internet Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:internet_plugindir]}`).",
}],
[:flag, "--audio_unit_plugindir=", {
description: "Target location for Audio Unit Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:audio_unit_plugindir]}`",
description: "Target location for Audio Unit Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:audio_unit_plugindir]}`).",
}],
[:flag, "--vst_plugindir=", {
description: "Target location for VST Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:vst_plugindir]}`",
description: "Target location for VST Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:vst_plugindir]}`).",
}],
[:flag, "--vst3_plugindir=", {
description: "Target location for VST3 Plugins. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:vst3_plugindir]}`",
description: "Target location for VST3 Plugins " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:vst3_plugindir]}`).",
}],
[:flag, "--screen_saverdir=", {
description: "Target location for Screen Savers. " \
"Default: `#{Cask::Config::DEFAULT_DIRS[:screen_saverdir]}`",
description: "Target location for Screen Savers " \
"(default: `#{Cask::Config::DEFAULT_DIRS[:screen_saverdir]}`).",
}],
[:comma_array, "--language", {
description: "Set language of the Cask to install. The first matching " \
"language is used, otherwise the default language on the Cask. " \
"The default value is the `language of your system`",
description: "Comma-separated list of language codes to prefer for cask installation. " \
"The first matching language is used, otherwise it reverts to the cask's " \
"default language. The default value is the language of your system.",
}],
]
end
Expand Down Expand Up @@ -176,7 +176,7 @@ def usage_banner(text)

def usage_banner_text
@parser.banner
.gsub(/^ - (`[^`]+`)\s+/, "\n- \\1 \n ") # Format `cask` subcommands as MarkDown list.
.gsub(/^ - (`[^`]+`)\s+/, "\n- \\1:\n <br>") # Format `cask` subcommands as Markdown list.
end

def comma_array(name, description: nil)
Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/cmd/--cache.rb
View file
Open in desktop
Expand Up @@ -16,7 +16,7 @@ module Homebrew
def __cache_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`--cache` [<options>] [<formula|cask>]
`--cache` [<options>] [<formula>|<cask>]

Display Homebrew's download cache. See also `HOMEBREW_CACHE`.

Expand Down
1 change: 1 addition & 0 deletions Library/Homebrew/cmd/--version.rb
View file
Open in desktop
Expand Up @@ -17,6 +17,7 @@ def __version_args
Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask
(if tapped) to standard output.
EOS

max_named 0
end
end
Expand Down
3 changes: 2 additions & 1 deletion Library/Homebrew/cmd/analytics.rb
View file
Open in desktop
Expand Up @@ -20,12 +20,13 @@ def analytics_args
`brew analytics` [`state`]:
Display the current state of Homebrew's analytics.

`brew analytics` [`on`|`off`]:
`brew analytics` (`on`|`off`):
Turn Homebrew's analytics on or off respectively.

`brew analytics regenerate-uuid`:
Regenerate the UUID used for Homebrew's analytics.
EOS

max_named 1
end
end
Expand Down
3 changes: 2 additions & 1 deletion Library/Homebrew/cmd/autoremove.rb
View file
Open in desktop
Expand Up @@ -17,7 +17,8 @@ def autoremove_args
EOS
switch "-n", "--dry-run",
description: "List what would be uninstalled, but do not actually uninstall anything."
named 0

max_named 0
end
end

Expand Down
2 changes: 0 additions & 2 deletions Library/Homebrew/cmd/install.rb
View file
Open in desktop
Expand Up @@ -85,7 +85,6 @@ def install_args
}],
[:switch, "--keep-tmp", {
description: "Retain the temporary files created during installation.",

}],
[:switch, "--build-bottle", {
description: "Prepare the formula for eventual bottling during installation, skipping any " \
Expand Down Expand Up @@ -125,7 +124,6 @@ def install_args

conflicts "--ignore-dependencies", "--only-dependencies"
conflicts "--build-from-source", "--build-bottle", "--force-bottle"

min_named :formula_or_cask
end
end
Expand Down
6 changes: 3 additions & 3 deletions Library/Homebrew/cmd/list.rb
View file
Open in desktop
Expand Up @@ -15,14 +15,14 @@ module Homebrew
def list_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`list`, `ls` [<options>] [<formula|cask>]
`list`, `ls` [<options>] [<formula>|<cask>]

List all installed formulae or casks
List all installed formulae and casks.

If <formula> is provided, summarise the paths within its current keg.
EOS
switch "--formula", "--formulae",
description: "List only formulae. `This is the default action on non TTY.`"
description: "List only formulae. This is the default when output is not to a terminal."
switch "--cask", "--casks",
description: "List only casks, or <cask> if provided."
switch "--unbrewed",
Expand Down
3 changes: 2 additions & 1 deletion Library/Homebrew/cmd/log.rb
View file
Open in desktop
Expand Up @@ -28,8 +28,9 @@ def log_args
description: "Print only one commit."
flag "-n", "--max-count=",
description: "Print only a specified number of commits."
max_named 1

conflicts "-1", "--max-count"
max_named 1
end
end

Expand Down
4 changes: 2 additions & 2 deletions Library/Homebrew/cmd/outdated.rb
View file
Open in desktop
Expand Up @@ -26,9 +26,9 @@ def outdated_args
switch "-v", "--verbose",
description: "Include detailed version information."
switch "--formula",
description: "Only output outdated formulae."
description: "List only outdated formulae."
switch "--cask",
description: "Only output outdated casks."
description: "List only outdated casks."
flag "--json",
description: "Print output in JSON format. There are two versions: v1 and v2. " \
"v1 is deprecated and is currently the default if no version is specified. " \
Expand Down
5 changes: 2 additions & 3 deletions Library/Homebrew/cmd/reinstall.rb
View file
Open in desktop
Expand Up @@ -45,8 +45,8 @@ def reinstall_args
}],
[:switch, "-i", "--interactive", {
description: "Download and patch <formula>, then open a shell. This allows the user to " \
"run `./configure --help` and otherwise determine how to turn the software " \
"package into a Homebrew package.",
"run `./configure --help` and otherwise determine how to turn the software " \
"package into a Homebrew package.",
}],
[:switch, "--force-bottle", {
description: "Install from a bottle if it exists for the current or newest version of " \
Expand Down Expand Up @@ -75,7 +75,6 @@ def reinstall_args
cask_options

conflicts "--build-from-source", "--force-bottle"

min_named :formula_or_cask
end
end
Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/cmd/search.rb
View file
Open in desktop
Expand Up @@ -50,7 +50,7 @@ def search_args
description: "Search for formulae with a description matching <text> and casks with "\
"a name matching <text>."
switch "--pull-request",
description: "Search for GitHub pull requests for <text>."
description: "Search for GitHub pull requests containing <text>."

package_manager_switches = PACKAGE_MANAGERS.keys.map { |name| "--#{name}" }
package_manager_switches.each do |s|
Expand Down
5 changes: 2 additions & 3 deletions Library/Homebrew/cmd/upgrade.rb
View file
Open in desktop
Expand Up @@ -47,8 +47,8 @@ def upgrade_args
}],
[:switch, "-i", "--interactive", {
description: "Download and patch <formula>, then open a shell. This allows the user to "\
"run `./configure --help` and otherwise determine how to turn the software "\
"package into a Homebrew package.",
"run `./configure --help` and otherwise determine how to turn the software "\
"package into a Homebrew package.",
}],
[:switch, "--force-bottle", {
description: "Install from a bottle if it exists for the current or newest version of "\
Expand All @@ -58,7 +58,6 @@ def upgrade_args
description: "Fetch the upstream repository to detect if the HEAD installation of the "\
"formula is outdated. Otherwise, the repository's HEAD will only be checked for "\
"updates when a new stable or development version has been released.",

}],
[:switch, "--ignore-pinned", {
description: "Set a successful exit status even if pinned formulae are not upgraded.",
Expand Down
1 change: 1 addition & 0 deletions Library/Homebrew/cmd/uses.rb
View file
Open in desktop
Expand Up @@ -40,6 +40,7 @@ def uses_args
description: "Include all formulae that specify <formula> as `:optional` type dependency."
switch "--skip-recommended",
description: "Skip all formulae that specify <formula> as `:recommended` type dependency."

min_named :formula
end
end
Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/dev-cmd/audit.rb
View file
Open in desktop
Expand Up @@ -54,7 +54,7 @@ def audit_args
"make output easy to grep."
switch "--skip-style",
description: "Skip running non-RuboCop style checks. Useful if you plan on running "\
"`brew style` separately. Default unless a formula is specified by name"
"`brew style` separately. Enabled by default unless a formula is specified by name."
switch "-D", "--audit-debug",
description: "Enable debugging and profiling of audit methods."
comma_array "--only",
Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/dev-cmd/bump-cask-pr.rb
View file
Open in desktop
Expand Up @@ -14,7 +14,7 @@ module Homebrew
def bump_cask_pr_args
Homebrew::CLI::Parser.new do
usage_banner <<~EOS
`bump-cask-pr` [<options>] [<cask>]
`bump-cask-pr` [<options>] <cask>

Create a pull request to update <cask> with a new version.

Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/dev-cmd/bump-formula-pr.rb
View file
Open in desktop
Expand Up @@ -73,7 +73,7 @@ def bump_formula_pr_args
depends_on: "--tag=",
description: "Specify the new git commit <revision> corresponding to the specified <tag>."
switch "-f", "--force",
description: "Ignore duplicate open PRs. Remove all mirrors if --mirror= was not specified."
description: "Ignore duplicate open PRs. Remove all mirrors if `--mirror` was not specified."

conflicts "--dry-run", "--write"
conflicts "--no-audit", "--strict"
Expand Down
4 changes: 2 additions & 2 deletions Library/Homebrew/dev-cmd/bump.rb
View file
Open in desktop
Expand Up @@ -17,8 +17,8 @@ def bump_args
Display out-of-date brew formulae and the latest version available.
Also displays whether a pull request has been opened with the URL.
EOS
flag "--limit=",
description: "Limit number of package results returned."
flag "--limit=",
description: "Limit number of package results returned."
switch :verbose
switch :debug
end
Expand Down
1 change: 1 addition & 0 deletions Library/Homebrew/dev-cmd/cat.rb
View file
Open in desktop
Expand Up @@ -16,6 +16,7 @@ def cat_args

Display the source of <formula>.
EOS

named :formula
end
end
Expand Down
2 changes: 1 addition & 1 deletion Library/Homebrew/dev-cmd/create.rb
View file
Open in desktop
Expand Up @@ -59,7 +59,7 @@ def create_args
flag "--tap=",
description: "Generate the new formula within the given tap, specified as <user>`/`<repo>."
switch "-f", "--force",
description: "Ignore errors for disallowed formula names and named that shadow aliases."
description: "Ignore errors for disallowed formula names and names that shadow aliases."

conflicts "--autotools", "--cmake", "--crystal", "--go", "--meson", "--node", "--perl", "--python", "--rust"
named 1
Expand Down
4 changes: 2 additions & 2 deletions Library/Homebrew/dev-cmd/dispatch-build-bottle.rb
View file
Open in desktop
Expand Up @@ -27,14 +27,14 @@ def dispatch_build_bottle_args
description: "Dispatch specified workflow (default: `dispatch-build-bottle.yml`)."
switch "--upload",
description: "Upload built bottles to Bintray."

min_named :formula
end
end

def dispatch_build_bottle
args = dispatch_build_bottle_args.parse

raise FormulaUnspecifiedError if args.named.empty?

odie "Must specify --macos option" unless args.macos

macos = begin
Expand Down
9 changes: 6 additions & 3 deletions Library/Homebrew/dev-cmd/man.rb
View file
Open in desktop
Expand Up @@ -30,6 +30,7 @@ def man_args
"comparison without factoring in the date)."
switch "--link",
description: "This is now done automatically by `brew update`."

max_named 0
end
end
Expand Down Expand Up @@ -135,6 +136,8 @@ def convert_man_page(markup, target, preserve_date:)
when "--markdown"
ronn_output = ronn_output.gsub(%r{<var>(.*?)</var>}, "*`\\1`*")
.gsub(/\n\n\n+/, "\n\n")
.gsub(/^(- `[^`]+`):/, "\\1") # drop trailing colons from definition lists
.gsub(/(?<=\n\n)([\[`].+):\n/, "\\1\n<br>") # replace colons with <br> on subcommands
when "--roff"
ronn_output = ronn_output.gsub(%r{<code>(.*?)</code>}, "\\fB\\1\\fR")
.gsub(%r{<var>(.*?)</var>}, "\\fI\\1\\fR")
Expand Down Expand Up @@ -217,7 +220,7 @@ def cmd_comment_manpage_lines(cmd_path)
def global_cask_options_manpage
lines = ["These options are applicable to subcommands accepting a `--cask` flag and all `cask` commands.\n"]
lines += Homebrew::CLI::Parser.global_cask_options.map do |_, long, description:, **|
generate_option_doc(nil, long, description)
generate_option_doc(nil, long.chomp("="), description)
end
lines.join("\n")
end
Expand All @@ -234,10 +237,10 @@ def global_options_manpage
sig { returns(String) }
def env_vars_manpage
lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|
entry = " * `#{env}`:\n #{hash[:description]}\n"
entry = "- `#{env}`:\n <br>#{hash[:description]}\n"
default = hash[:default_text]
default ||= "`#{hash[:default]}`." if hash[:default]
entry += "\n\n *Default:* #{default}\n" if default
entry += "\n\n *Default:* #{default}\n" if default

entry
end
Expand Down