docs: add terminology to manpage

Library/Homebrew/dev-cmd/generate-man-completions.rb

@@ -67,6 +67,7 @@ module Homebrew
       generate_cmd_manpages(Commands.official_external_commands_paths(quiet: quiet))
     variables[:global_cask_options] = global_cask_options_manpage
     variables[:global_options] = global_options_manpage
+    variables[:terminology] = terminology_manpage
     variables[:environment_variables] = env_vars_manpage
 
     readme = HOMEBREW_REPOSITORY/"README.md"
@@ -229,6 +230,22 @@ module Homebrew
     lines.join("\n")
   end
 
+  sig { returns(String) }
+  def terminology_manpage
+    formula_cookbook_text = (HOMEBREW_REPOSITORY/"docs/Formula-Cookbook.md").read.split("\n")
+
+    start_term = "## Homebrew terminology"
+    start_index = formula_cookbook_text.index(start_term) + 4 # Skip ahead to the table contents
+    end_index = formula_cookbook_text.index "## An introduction"
+    formula_cookbook_text[start_index...end_index].map do |item|
+      next "" unless item.include? "|"
+
+      term, definition, example = item.split("|").map(&:strip)[1..]
+      definition.gsub!(/\[(.*)\]\(.*\)/, '\1')
+      "#{term}: #{definition} (e.g. #{example})"
+    end.join("\n\n")
+  end
+
   sig { returns(String) }
   def env_vars_manpage
     lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|

Library/Homebrew/manpages/brew.1.md.erb

@@ -137,6 +137,10 @@ And for an authenticated HTTP proxy:
 
     export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT
 
+## TERMINOLOGY
+
+<%= terminology %>
+
 ## SEE ALSO
 
 Homebrew Documentation: <https://docs.brew.sh>

docs/Manpage.md

@@ -2052,6 +2052,24 @@ And for an authenticated HTTP proxy:
 
     export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT
 
+## TERMINOLOGY
+
+**Formula**: The package definition (e.g. `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb`)
+
+**Keg**: The installation prefix of a **Formula** (e.g. `/usr/local/Cellar/foo/0.1`)
+
+**opt prefix**: A symlink to the active version of a **Keg** (e.g. `/usr/local/opt/foo`)
+
+**Cellar**: All **Kegs** are installed here (e.g. `/usr/local/Cellar`)
+
+**Tap**: A Git repository of **Formulae** and/or commands (e.g. `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`)
+
+**Bottle**: Pre-built **Keg** used instead of building from source (e.g. `qt-4.8.4.catalina.bottle.tar.gz`)
+
+**Cask**: An extension of Homebrew to install macOS native apps (e.g. `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown`)
+
+**Brew Bundle**: An extension of Homebrew to describe dependencies (e.g. `brew 'myservice', restart_service: true`)
+
 ## SEE ALSO
 
 Homebrew Documentation: <https://docs.brew.sh>
@@ -2100,6 +2118,7 @@ See our issues on GitHub:
 [SPECIFYING CASKS]: #SPECIFYING-CASKS "SPECIFYING CASKS"
 [ENVIRONMENT]: #ENVIRONMENT "ENVIRONMENT"
 [USING HOMEBREW BEHIND A PROXY]: #USING-HOMEBREW-BEHIND-A-PROXY "USING HOMEBREW BEHIND A PROXY"
+[TERMINOLOGY]: #TERMINOLOGY "TERMINOLOGY"
 [SEE ALSO]: #SEE-ALSO "SEE ALSO"
 [AUTHORS]: #AUTHORS "AUTHORS"
 [BUGS]: #BUGS "BUGS"

manpages/brew.1

@@ -2988,6 +2988,38 @@ export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT
 .
 .IP "" 0
 .
+.SH "TERMINOLOGY"
+\fBFormula\fR
+    The package definition (e\.g\. \fB/usr/local/Homebrew/Library/Taps/homebrew/homebrew\-core/Formula/foo\.rb\fR)
+.
+.P
+\fBKeg\fR
+    The installation prefix of a \fBFormula\fR (e\.g\. \fB/usr/local/Cellar/foo/0\.1\fR)
+.
+.P
+\fBopt prefix\fR
+    A symlink to the active version of a \fBKeg\fR (e\.g\. \fB/usr/local/opt/foo\fR)
+.
+.P
+\fBCellar\fR
+    All \fBKegs\fR are installed here (e\.g\. \fB/usr/local/Cellar\fR)
+.
+.P
+\fBTap\fR
+    A Git repository of \fBFormulae\fR and/or commands (e\.g\. \fB/usr/local/Homebrew/Library/Taps/homebrew/homebrew\-core\fR)
+.
+.P
+\fBBottle\fR
+    Pre\-built \fBKeg\fR used instead of building from source (e\.g\. \fBqt\-4\.8\.4\.catalina\.bottle\.tar\.gz\fR)
+.
+.P
+\fBCask\fR
+    An extension of Homebrew to install macOS native apps (e\.g\. \fB/Applications/MacDown\.app/Contents/SharedSupport/bin/macdown\fR)
+.
+.P
+\fBBrew Bundle\fR: An extension of Homebrew to describe dependencies (e\.g\. \fBbrew \'myservice\', restart_service
+    true\fR)
+.
 .SH "SEE ALSO"
 Homebrew Documentation: \fIhttps://docs\.brew\.sh\fR
 .