mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Separate terminology from cookbook and manpages

Browse Source
This commit is contained in:
Rylan Polster 2021-06-07 10:57:27 -04:00
parent 144c1c68c3
commit 2c22a258a0
No known key found for this signature in database
GPG Key ID: 46A744940CFF4D64
5 changed files with 71 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
Library/Homebrew/dev-cmd/generate-man-completions.rb
View File

@ -67,7 +67,6 @@ module Homebrew
generate_cmd_manpages(Commands.official_external_commands_paths(quiet: quiet)) generate_cmd_manpages(Commands.official_external_commands_paths(quiet: quiet))
variables[:global_cask_options] = global_cask_options_manpage variables[:global_cask_options] = global_cask_options_manpage
variables[:global_options] = global_options_manpage variables[:global_options] = global_options_manpage
variables[:terminology] = terminology_manpage
variables[:environment_variables] = env_vars_manpage variables[:environment_variables] = env_vars_manpage
readme = HOMEBREW_REPOSITORY/"README.md" readme = HOMEBREW_REPOSITORY/"README.md"
@ -230,22 +229,6 @@ module Homebrew
lines.join("\n") lines.join("\n")
end 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) } sig { returns(String) }
def env_vars_manpage def env_vars_manpage
lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash| lines = Homebrew::EnvConfig::ENVS.flat_map do |env, hash|

22
Library/Homebrew/manpages/brew.1.md.erb
View File

@ -28,6 +28,24 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple
didn't include with macOS. It can also install software not packaged for your didn't include with macOS. It can also install software not packaged for your
Linux distribution to your home directory without requiring `sudo`. Linux distribution to your home directory without requiring `sudo`.
## TERMINOLOGY
**Formula**: The package definition
**Cask**: An extension of Homebrew to install macOS native apps
**Keg**: The installation prefix of a **Formula**
**Keg-only**: A **Formula** is **Keg-only** if it is not linked into the Homebrew prefix
**Cellar**: All **Kegs** are installed here
**Caskroom**: All **Casks** are installed here
**Tap**: A Git repository of **Formulae** and/or commands
**Bottle**: Pre-built **Keg** used instead of building from source
## ESSENTIAL COMMANDS ## ESSENTIAL COMMANDS
For the full command list, see the [COMMANDS](#commands) section. For the full command list, see the [COMMANDS](#commands) section.
@ -137,10 +155,6 @@ And for an authenticated HTTP proxy:
export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT
## TERMINOLOGY
<%= terminology %>
## SEE ALSO ## SEE ALSO
Homebrew Documentation: <https://docs.brew.sh> Homebrew Documentation: <https://docs.brew.sh>

1
docs/Formula-Cookbook.md
View File

@ -8,6 +8,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
|----------------|------------------------------------------------------------|-----------------------------------------------------------------| |----------------|------------------------------------------------------------|-----------------------------------------------------------------|
| **Formula** | The package definition | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` | | **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** | 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` formula](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openjdk.rb) |
| **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` | | **opt prefix** | A symlink to the active version of a **Keg** | `/usr/local/opt/foo ` |
| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` | | **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` | | **Tap** | A Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` |

38
docs/Manpage.md
View File

@ -12,6 +12,24 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple
didn't include with macOS. It can also install software not packaged for your didn't include with macOS. It can also install software not packaged for your
Linux distribution to your home directory without requiring `sudo`. Linux distribution to your home directory without requiring `sudo`.
## TERMINOLOGY
**Formula**: The package definition
**Cask**: An extension of Homebrew to install macOS native apps
**Keg**: The installation prefix of a **Formula**
**Keg-only**: A **Formula** is **Keg-only** if it is not linked into the Homebrew prefix
**Cellar**: All **Kegs** are installed here
**Caskroom**: All **Casks** are installed here
**Tap**: A Git repository of **Formulae** and/or commands
**Bottle**: Pre-built **Keg** used instead of building from source
## ESSENTIAL COMMANDS ## ESSENTIAL COMMANDS
For the full command list, see the [COMMANDS](#commands) section. For the full command list, see the [COMMANDS](#commands) section.
@ -2052,24 +2070,6 @@ And for an authenticated HTTP proxy:
export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT 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 ## SEE ALSO
Homebrew Documentation: <https://docs.brew.sh> Homebrew Documentation: <https://docs.brew.sh>
@ -2107,6 +2107,7 @@ See our issues on GitHub:
[SYNOPSIS]: #SYNOPSIS "SYNOPSIS" [SYNOPSIS]: #SYNOPSIS "SYNOPSIS"
[DESCRIPTION]: #DESCRIPTION "DESCRIPTION" [DESCRIPTION]: #DESCRIPTION "DESCRIPTION"
[TERMINOLOGY]: #TERMINOLOGY "TERMINOLOGY"
[ESSENTIAL COMMANDS]: #ESSENTIAL-COMMANDS "ESSENTIAL COMMANDS" [ESSENTIAL COMMANDS]: #ESSENTIAL-COMMANDS "ESSENTIAL COMMANDS"
[COMMANDS]: #COMMANDS "COMMANDS" [COMMANDS]: #COMMANDS "COMMANDS"
[DEVELOPER COMMANDS]: #DEVELOPER-COMMANDS "DEVELOPER COMMANDS" [DEVELOPER COMMANDS]: #DEVELOPER-COMMANDS "DEVELOPER COMMANDS"
@ -2118,7 +2119,6 @@ See our issues on GitHub:
[SPECIFYING CASKS]: #SPECIFYING-CASKS "SPECIFYING CASKS" [SPECIFYING CASKS]: #SPECIFYING-CASKS "SPECIFYING CASKS"
[ENVIRONMENT]: #ENVIRONMENT "ENVIRONMENT" [ENVIRONMENT]: #ENVIRONMENT "ENVIRONMENT"
[USING HOMEBREW BEHIND A PROXY]: #USING-HOMEBREW-BEHIND-A-PROXY "USING HOMEBREW BEHIND A PROXY" [USING HOMEBREW BEHIND A PROXY]: #USING-HOMEBREW-BEHIND-A-PROXY "USING HOMEBREW BEHIND A PROXY"
[TERMINOLOGY]: #TERMINOLOGY "TERMINOLOGY"
[SEE ALSO]: #SEE-ALSO "SEE ALSO" [SEE ALSO]: #SEE-ALSO "SEE ALSO"
[AUTHORS]: #AUTHORS "AUTHORS" [AUTHORS]: #AUTHORS "AUTHORS"
[BUGS]: #BUGS "BUGS" [BUGS]: #BUGS "BUGS"

64
manpages/brew.1
View File

@ -15,6 +15,38 @@
.SH "DESCRIPTION" .SH "DESCRIPTION"
Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn\'t include with macOS\. It can also install software not packaged for your Linux distribution to your home directory without requiring \fBsudo\fR\. Homebrew is the easiest and most flexible way to install the UNIX tools Apple didn\'t include with macOS\. It can also install software not packaged for your Linux distribution to your home directory without requiring \fBsudo\fR\.
. .
.SH "TERMINOLOGY"
\fBFormula\fR
The package definition
.
.P
\fBCask\fR
An extension of Homebrew to install macOS native apps
.
.P
\fBKeg\fR
The installation prefix of a \fBFormula\fR
.
.P
\fBKeg\-only\fR
A \fBFormula\fR is \fBKeg\-only\fR if it is not linked into the Homebrew prefix
.
.P
\fBCellar\fR
All \fBKegs\fR are installed here
.
.P
\fBCaskroom\fR
All \fBCasks\fR are installed here
.
.P
\fBTap\fR
A Git repository of \fBFormulae\fR and/or commands
.
.P
\fBBottle\fR
Pre\-built \fBKeg\fR used instead of building from source
.
.SH "ESSENTIAL COMMANDS" .SH "ESSENTIAL COMMANDS"
For the full command list, see the \fICOMMANDS\fR section\. For the full command list, see the \fICOMMANDS\fR section\.
. .
@ -2988,38 +3020,6 @@ export http_proxy=http://$USER:$PASSWORD@$HOST:$PORT
. .
.IP "" 0 .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" .SH "SEE ALSO"
Homebrew Documentation: \fIhttps://docs\.brew\.sh\fR Homebrew Documentation: \fIhttps://docs\.brew\.sh\fR
. .