Formula-Cookbook: expand terminology table

Homebrew · Aug 13, 2023 · 569c833 · 569c833
1 parent 7044f50
commit 569c833
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 33 deletions.
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
@@ -30,25 +30,29 @@ Linux distribution without requiring `sudo`.
 
 ## TERMINOLOGY
 
-**formula**: Homebrew package definition built from upstream sources
+**formula**: Homebrew package definition that builds from upstream sources
 
 **cask**: Homebrew package definition that installs macOS native applications
 
-**keg**: installation destination directory of a given **formula** version e.g. `/usr/local/Cellar/foo/0.1`
+**prefix**: path in which Homebrew is installed, e.g. `/usr/local`
 
-**rack**: directory containing one or more versioned kegs e.g. `/usr/local/Cellar/foo`
+**keg**: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`
 
-**keg-only**: a **formula** is **keg-only** if it is not symlinked into Homebrew's prefix (e.g. `/usr/local`)
+**rack**: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`
 
-**cellar**: directory containing one or more named **racks** e.g. `/usr/local/Cellar`
+**keg-only**: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix
 
-**Caskroom**: directory containing one or more named **casks** e.g. `/usr/local/Caskroom`
+**opt prefix**: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`
+
+**Cellar**: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`
+
+**Caskroom**: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`
 
 **external command**: `brew` subcommand defined outside of the Homebrew/brew GitHub repository
 
 **tap**: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**
 
-**bottle**: pre-built **keg** poured into the **cellar**/**rack** instead of building from upstream sources
+**bottle**: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources
 
 ## ESSENTIAL COMMANDS
 

diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
@@ -7,17 +7,22 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
 
 ## Homebrew terminology
 
-| term           | description                                                | example |
-| -------------- | ---------------------------------------------------------- | ------- |
-| **Formula**    | the package definition                                     | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb`
-| **Keg**        | the installation prefix of a **Formula**                   | `/usr/local/Cellar/foo/0.1`
-| **Keg-only**   | a **Formula** is **Keg-only** if it is not linked into the Homebrew prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openjdk.rb) formula
-| **opt prefix** | a symlink to the active version of a **Keg**               | `/usr/local/opt/foo`
-| **Cellar**     | all **Kegs** are installed here                            | `/usr/local/Cellar`
-| **Tap**        | a Git repository of **Formulae** and/or commands           | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`
-| **Bottle**     | pre-built **Keg** used instead of building from source     | `qt-4.8.4.catalina.bottle.tar.gz`
-| **Cask**       | an [extension of Homebrew](https://github.com/Homebrew/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown`
-| **Brew Bundle**| an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies   | `brew 'myservice', restart_service: true`
+| term                 | description                                                               | example |
+| -------------------- | ------------------------------------------------------------------------- | ------- |
+| **formula**          | Homebrew package definition that builds from upstream sources             | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb`
+| **cask**             | Homebrew package definition that installs macOS native applications       | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/bar.rb`
+| **prefix**           | path in which Homebrew is installed                                       | `/usr/local`
+| **keg**              | installation destination directory of a given **formula** version         | `/usr/local/Cellar/foo/0.1`
+| **rack**             | directory containing one or more versioned **kegs**                       | `/usr/local/Cellar/foo`
+| **keg-only**         | a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openjdk.rb) formula
+| **opt prefix**       | a symlink to the active version of a **keg**                              | `/usr/local/opt/foo`
+| **Cellar**           | directory containing one or more named **racks**                          | `/usr/local/Cellar`
+| **Caskroom**         | directory containing one or more named **casks**                          | `/usr/local/Caskroom`
+| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository  | [`brew alias`](https://github.com/Homebrew/homebrew-aliases)
+| **tap**              | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**       | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`
+| **bottle**           | pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources | `qt--6.5.1.ventura.bottle.tar.gz`
+| **Brew Bundle**      | an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies     | `brew 'myservice', restart_service: true`
+| **Brew Services**    | an [extension of Homebrew](https://github.com/Homebrew/homebrew-services) to manage services         | `brew services start myservice`
 
 ## An introduction
 

diff --git a/docs/Manpage.md b/docs/Manpage.md
@@ -14,25 +14,29 @@ Linux distribution without requiring `sudo`.
 
 ## TERMINOLOGY
 
-**formula**: Homebrew package definition built from upstream sources
+**formula**: Homebrew package definition that builds from upstream sources
 
 **cask**: Homebrew package definition that installs macOS native applications
 
-**keg**: installation destination directory of a given **formula** version e.g. `/usr/local/Cellar/foo/0.1`
+**prefix**: path in which Homebrew is installed, e.g. `/usr/local`
 
-**rack**: directory containing one or more versioned kegs e.g. `/usr/local/Cellar/foo`
+**keg**: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`
 
-**keg-only**: a **formula** is **keg-only** if it is not symlinked into Homebrew's prefix (e.g. `/usr/local`)
+**rack**: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`
 
-**cellar**: directory containing one or more named **racks** e.g. `/usr/local/Cellar`
+**keg-only**: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix
 
-**Caskroom**: directory containing one or more named **casks** e.g. `/usr/local/Caskroom`
+**opt prefix**: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`
+
+**Cellar**: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`
+
+**Caskroom**: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`
 
 **external command**: `brew` subcommand defined outside of the Homebrew/brew GitHub repository
 
 **tap**: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**
 
-**bottle**: pre-built **keg** poured into the **cellar**/**rack** instead of building from upstream sources
+**bottle**: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources
 
 ## ESSENTIAL COMMANDS
 

diff --git a/manpages/brew.1 b/manpages/brew.1
@@ -17,31 +17,39 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple di
 .
 .SH "TERMINOLOGY"
 \fBformula\fR
-    Homebrew package definition built from upstream sources
+    Homebrew package definition that builds from upstream sources
 .
 .P
 \fBcask\fR
     Homebrew package definition that installs macOS native applications
 .
 .P
+\fBprefix\fR
+    path in which Homebrew is installed, e\.g\. \fB/usr/local\fR
+.
+.P
 \fBkeg\fR
-    installation destination directory of a given \fBformula\fR version e\.g\. \fB/usr/local/Cellar/foo/0\.1\fR
+    installation destination directory of a given \fBformula\fR version, e\.g\. \fB/usr/local/Cellar/foo/0\.1\fR
 .
 .P
 \fBrack\fR
-    directory containing one or more versioned kegs e\.g\. \fB/usr/local/Cellar/foo\fR
+    directory containing one or more versioned \fBkegs\fR, e\.g\. \fB/usr/local/Cellar/foo\fR
 .
 .P
 \fBkeg\-only\fR
-    a \fBformula\fR is \fBkeg\-only\fR if it is not symlinked into Homebrew\'s prefix (e\.g\. \fB/usr/local\fR)
+    a \fBformula\fR is \fIkeg\-only\fR if it is not symlinked into Homebrew\'s prefix
+.
+.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
-    directory containing one or more named \fBracks\fR e\.g\. \fB/usr/local/Cellar\fR
+\fBCellar\fR
+    directory containing one or more named \fBracks\fR, e\.g\. \fB/usr/local/Cellar\fR
 .
 .P
 \fBCaskroom\fR
-    directory containing one or more named \fBcasks\fR e\.g\. \fB/usr/local/Caskroom\fR
+    directory containing one or more named \fBcasks\fR, e\.g\. \fB/usr/local/Caskroom\fR
 .
 .P
 \fBexternal command\fR
@@ -53,7 +61,7 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple di
 .
 .P
 \fBbottle\fR
-    pre\-built \fBkeg\fR poured into the \fBcellar\fR/\fBrack\fR instead of building from upstream sources
+    pre\-built \fBkeg\fR poured into a \fBrack\fR of the \fBCellar\fR instead of building from upstream sources
 .
 .SH "ESSENTIAL COMMANDS"
 For the full command list, see the \fICOMMANDS\fR section\.