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: localize internal URLs

Browse Source
This commit is contained in:
Eric Knibbe 2025-05-22 10:40:58 -04:00
parent 3f450e5f10
commit 6a07851c46
No known key found for this signature in database
15 changed files with 45 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -172,6 +172,7 @@
# Ignore generated documentation site
/docs/_site
/docs/.jekyll-metadata
/docs/tmp/.htmlproofer
/docs/vendor
/docs/Gemfile.lock

14
docs/.mdl_ruleset.rb
View File

@ -8,3 +8,17 @@ rule "HB034", "Bare unstyled URL used" do
doc.matching_text_element_lines(%r{(?<=\s)https?://})
end
end
rule "HB100", "Full URL for internal link used" do
tags :links, :url
aliases "no-full-urls-for-internal-links"
check do |doc|
doc.matching_lines(%r{\]\(https://docs.brew.sh/.+?\)})
end
end
rule "HB101", "File extension missing from internal link" do
tags :links, :url
aliases "file-extension-required-for-internal-links"
check do |doc|
doc.matching_lines(/\]\((?!#|\w+:)(?>[^#.)]+)(?!\.\w+)/)
end
end

6
docs/Acceptable-Casks.md
View File

@ -36,7 +36,7 @@ These versions also live in the main repository at [Homebrew/homebrew-cask](http
### Regional and Localized
When an app exists in more than one language or has different regional editions, [the `language` stanza should be used to switch between languages or regions](https://docs.brew.sh/Cask-Cookbook#stanza-language).
When an app exists in more than one language or has different regional editions, [the `language` stanza should be used to switch between languages or regions](Cask-Cookbook.md#stanza-language).
### Trial and Freemium versions
@ -111,7 +111,7 @@ Common reasons to reject a cask entirely:
* An app from a code repository that is not notable enough (under 30 forks, 30 watchers, 75 stars).
* [Electronic Identification (eID) software](https://github.com/Homebrew/homebrew-cask/issues/59021).
* App requires [SIP to be disabled](https://github.com/Homebrew/homebrew-cask/pull/41890) to be installed and/or used.
* App installer is a `pkg` that requires [`allow_untrusted: true`](https://docs.brew.sh/Cask-Cookbook#pkg-allow_untrusted).
* App installer is a `pkg` that requires [`allow_untrusted: true`](Cask-Cookbook.md#pkg-allow_untrusted).
* App is a trial version, and the only way to acquire the full version is through the Mac App Store.
* Similarly (and trickier to spot), the app has moved to the Mac App Store but still provides old versions via direct download. We reject these in all official repositories so users don’t get stuck using an old version, wrongly thinking they’re using the most up-to-date one (which, amongst other things, might be a security risk).
* App is unmaintained, i.e. no releases in the last year, or [explicitly discontinued](https://github.com/Homebrew/homebrew-cask/pull/22699).
@ -120,7 +120,7 @@ Common reasons to reject a cask entirely:
* Or if the Cask has a download URL that is both behind a login/registration form and from a host that differs from the homepage.
* Cask is unreasonably difficult to maintain. Examples have included [Audacity](https://github.com/Homebrew/homebrew-cask/pull/27517) and [older Java development casks](https://github.com/Homebrew/homebrew-cask/issues/57387).
* Cask has been rejected before due to an issue we cannot fix, and the new submission doesn’t fix that. An example would be the [first submission of `soapui`](https://github.com/Homebrew/homebrew-cask/pull/4939), whose installation problems were not fixed in the two [subsequent](https://github.com/Homebrew/homebrew-cask/pull/9969) [submissions](https://github.com/Homebrew/homebrew-cask/pull/10606).
* Cask is a duplicate. These submissions mostly occur when the [token reference](https://docs.brew.sh/Cask-Cookbook#token-reference) was not followed.
* Cask is a duplicate. These submissions mostly occur when the [token reference](Cask-Cookbook.md#token-reference) was not followed.
* The author has [specifically asked us not to include it](https://github.com/Homebrew/homebrew-cask/pull/5342).
* App is both open-source and CLI-only (i.e. it only uses the `binary` artifact). In that case, and [in the spirit of deduplication](https://github.com/Homebrew/homebrew-cask/issues/15603), submit it first to [homebrew/core](https://github.com/Homebrew/homebrew-core) as a formula that builds from source. If it is rejected, you may then try again as a cask (link to the issue from your pull request so we can see the discussion and reasoning for rejection).
* App is open-source and has a GUI but no compiled versions (or only old ones) are provided. It’s better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don’t get perpetually outdated versions. See [`gedit`](https://github.com/Homebrew/homebrew-cask/pull/23360) for example.

2
docs/Brew-Bundle-and-Brewfile.md
View File

@ -10,7 +10,7 @@ It uses `Brewfile`s to provide a declarative interface for installing/upgrading
Rather than specifying the `brew` commands you wish to run, you can specify the state you wish to reach.
See also the [`brew bundle` section of `man brew`](https://docs.brew.sh/Manpage#bundle-subcommand) or `brew bundle --help`.
See also the [`brew bundle` section of `man brew`](Manpage.md#bundle-subcommand) or `brew bundle --help`.
## Basic Usage

8
docs/Common-Issues.md
View File

@ -229,7 +229,7 @@ Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEA
### Cask - source is not there
First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` then the problem is with the [`app`](https://docs.brew.sh/Cask-Cookbook#stanza-app) stanza. This pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required).
First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` then the problem is with the [`app`](Cask-Cookbook.md#stanza-app) stanza. This pattern is the same across [all artifacts](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required).
Fixing this error is typically easy, and requires only a bit of time on your part. Start by downloading the package for the cask: `brew fetch <cask_name>`. The last line of output will inform you of the location of the download. Navigate there and manually unpack it. As an example, let's say the structure inside the archive is as follows:
@ -246,19 +246,19 @@ Now, if we find this when looking at the cask with `brew cat <cask_name>`:
The cask expects `SomeApp.app` to be in the top directory of the archive (see how it says simply `SomeApp.app`) but the developer has since moved it to be inside a `Files` directory. All we have to do is update that line of the cask to follow the new structure: `app "Files/SomeApp.app"`.
Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](https://docs.brew.sh/Cask-Cookbook#token-reference) for complete instructions on the new name.
Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](Cask-Cookbook.md#token-reference) for complete instructions on the new name.
Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
### Cask - wrong number of arguments
Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](https://docs.brew.sh/Cask-Cookbook#depends_on-macos) stanza to prevent the cask from being installed on incompatible macOS versions.
Make sure the issue really lies with your macOS version. To do so, try to install the software manually. If it is incompatible with your macOS version, it will tell you. In that case, there is nothing we can do to help you install the software, but we can add a [`depends_on macos:`](Cask-Cookbook.md#depends_on-macos) stanza to prevent the cask from being installed on incompatible macOS versions.
Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.
## Other local issues
If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use `brew bundle` to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew), [reinstall](https://docs.brew.sh/Installation) and run `brew bundle install`.
If your Homebrew installation gets messed up (and fixing the issues found by `brew doctor` doesn't solve the problem), reinstalling Homebrew may help to reset to a normal state. To easily reinstall Homebrew, use `brew bundle` to automatically restore your installed formulae and casks. To do so, run `brew bundle dump`, [uninstall](FAQ.md#how-do-i-uninstall-homebrew), [reinstall](Installation.md) and run `brew bundle install`.
## Possible `curl` issues

2
docs/FAQ.md
View File

@ -222,7 +222,7 @@ There are a few ideas to fix this problem:
So we let software be. Anything installed with Homebrew Cask should behave the same as if it were installed manually. But since we also want to support software that doesn’t self-upgrade, we add [`auto_updates true`](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/a/alfred.rb#L18) to casks for software that does, which excludes them from `brew upgrade`.
Casks which use `version :latest` are also excluded, because we have no way to track their installed version. It helps to ask the developers of such software to provide versioned releases (i.e. include the version in the path of the download `url`).
Casks which use [`version :latest`](Cask-Cookbook.md#special-value-latest) are also excluded, because we have no way to track their installed version. It helps to ask the developers of such software to provide versioned releases (i.e. include the version in the path of the download `url`).
If you still want to force software to be upgraded via Homebrew Cask, you can reference it specifically in the `upgrade` command:

4
docs/Formula-Cookbook.md
View File

@ -43,7 +43,7 @@ Packages are installed according to their formulae. Read over a simple one, e.g.
Make sure you run `brew update` before you start. This ensures your Homebrew installation is a Git repository.
To create or edit formulae locally, you'll need to first [tap `homebrew/core`](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself) if you haven't previously. This clones the Homebrew/homebrew-core Git repository to `$(brew --repository homebrew/core)`. As you're developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment or before any `install`, `reinstall` or `upgrade` commands to force `brew` to use the local repository instead of the API.
To create or edit formulae locally, you'll need to first [tap `homebrew/core`](FAQ.md#can-i-edit-formulae-myself) if you haven't previously. This clones the Homebrew/homebrew-core Git repository to `$(brew --repository homebrew/core)`. As you're developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment or before any `install`, `reinstall` or `upgrade` commands to force `brew` to use the local repository instead of the API.
Before submitting a new formula make sure your package:
@ -433,7 +433,7 @@ If you have already forked Homebrew on GitHub, then you can manually push (just
git push https://github.com/myname/homebrew-core/ <what-you-named-your-branch>
```
Now, [open a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request) for your changes.
Now, [open a pull request](How-To-Open-a-Homebrew-Pull-Request.md) for your changes.
* One formula per commit; one commit per formula.
* Keep merge commits out of the pull request.

2
docs/Homebrew-and-Python.md
View File

@ -11,7 +11,7 @@ Homebrew will install the necessary Python 3 version that is needed to make your
## Python 3
Homebrew provides formulae for the newest and maintained releases of Python 3 (`python@3.y`) (<https://devguide.python.org/versions/>).
We keep older `python@3.y` versions according to our [versioned formulae guidelines](https://docs.brew.sh/Versions).
We keep older `python@3.y` versions according to our [versioned formulae guidelines](Versions.md).
**Important:** Python may be upgraded to a newer version at any time. Consider using a version
manager such as `pyenv` if you require stability of minor or patch versions for virtual environments.

2
docs/Homebrew-on-Linux.md
View File

@ -76,7 +76,7 @@ To install build tools, paste at a terminal prompt:
### ARM32 (Tier 3 Support)
Homebrew can run on 32-bit ARM (e.g. Raspberry Pi and others), but as they lack bottles (binary packages) they are a [Tier 3 supported platform](https://docs.brew.sh/Support-Tiers#tier-3)
Homebrew can run on 32-bit ARM systems (e.g. Raspberry Pi and others), but as they lack bottles (binary packages) they are a [Tier 3 supported platform](Support-Tiers.md#tier-3).
You may need to install your own Ruby using your system package manager, a PPA, or `rbenv/ruby-build` as we don't distribute a Homebrew Portable Ruby for ARM32.

8
docs/How-To-Open-a-Homebrew-Pull-Request.md
View File

@ -10,11 +10,11 @@ The type of change you want to make influences which of Homebrew's main reposito
## Submit a new version of an existing formula
1. Use [`brew bump-formula-pr`](Manpage#bump-formula-pr-options-formula) to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more.
1. Use [`brew bump-formula-pr`](Manpage.md#bump-formula-pr-options-formula) to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more.
## Submit a new version of an existing cask
1. Use [`brew bump-cask-pr`](Manpage#bump-cask-pr-options-cask) to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-cask-pr --help` to learn more.
1. Use [`brew bump-cask-pr`](Manpage.md#bump-cask-pr-options-cask) to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-cask-pr --help` to learn more.
## Set up your own fork of the Homebrew repository
@ -38,7 +38,7 @@ The type of change you want to make influences which of Homebrew's main reposito
### Formulae-related pull request
Before creating a new formula, please read [Acceptable Formulae](https://docs.brew.sh/Acceptable-Formulae).
Before creating a new formula, please read [Acceptable Formulae](Acceptable-Formulae.md).
1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork).
* This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
@ -64,7 +64,7 @@ Before creating a new formula, please read [Acceptable Formulae](https://docs.br
### Cask-related pull request
Before creating a new cask, please read [Acceptable Casks](https://docs.brew.sh/Acceptable-Casks).
Before creating a new cask, please read [Acceptable Casks](Acceptable-Casks.md).
1. [Fork the Homebrew/homebrew-cask repository on GitHub](https://github.com/Homebrew/homebrew-cask/fork).
* This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.

6
docs/Installation.md
View File

@ -104,12 +104,12 @@ eval "$(<Homebrew prefix path>/bin/brew shellenv)"
```
Replace `<Homebrew prefix path>` with the directory where Homebrew is installed on your system.
You can find Homebrew's default install location [in this FAQ entry](https://docs.brew.sh/FAQ#why-should-i-install-homebrew-in-the-default-location).
You can find Homebrew's default install location in [this FAQ entry](FAQ.md#why-should-i-install-homebrew-in-the-default-location).
For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/deacfa6a6e62e5f4002baf9e1fac7a96e9aa5d41/install.sh#L1072-L1088)
For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/956abfa01f0d1dba285e6d3da86587ed428f19fe/install.sh#L1075-L1091)
to see how the installer constructs the path it recommends.
See [Tips and Tricks > Loading Homebrew from the same dotfiles on different operating systems](Tips-and-Tricks.md#loading-homebrew-from-the-same-dotfiles-on-different-operating-systems)
See [this tip in Tips and Tricks](Tips-and-Tricks.md#load-homebrew-from-the-same-dotfiles-on-different-operating-systems)
for another way to handle this across multiple operating systems.
## Uninstallation

6
docs/New-Maintainer-Checklist.md
View File

@ -82,7 +82,7 @@ Now sit back, relax and let the new maintainers handle more of our contributions
## PLC
If a maintainer or member is elected to the Homebrew's [Project Leadership Committee](https://docs.brew.sh/Homebrew-Governance#4-project-leadership-committee):
If a maintainer or member is elected to the Homebrew's [Project Leadership Committee](Homebrew-Governance.md#4-project-leadership-committee):
- Invite them to the [**@Homebrew/plc** team](https://github.com/orgs/Homebrew/teams/plc/members)
- Make them [billing managers](https://github.com/organizations/Homebrew/settings/billing) and [moderators](https://github.com/organizations/Homebrew/settings/moderators) on the Homebrew GitHub organisation
@ -92,7 +92,7 @@ When they cease to be a PLC member, revoke or downgrade their access to all of t
## TSC
If a maintainer is elected to the Homebrew's [Technical Steering Committee](https://docs.brew.sh/Homebrew-Governance#7-technical-steering-committee):
If a maintainer is elected to the Homebrew's [Technical Steering Committee](Homebrew-Governance.md#7-technical-steering-committee):
- Invite them to the [**@Homebrew/tsc** team](https://github.com/orgs/Homebrew/teams/tsc/members)
- Make them [billing managers](https://github.com/organizations/Homebrew/settings/billing) and [moderators](https://github.com/organizations/Homebrew/settings/moderators) on the Homebrew GitHub organisation
@ -111,7 +111,7 @@ When they cease to be an owner, revoke or downgrade their access to all of the a
## Members
People who are either not eligible or willing to be Homebrew maintainers but have shown continued involvement in the Homebrew community may be admitted by a majority vote of the [Project Leadership Committee](https://docs.brew.sh/Homebrew-Governance#4-project-leadership-committee).
People who are either not eligible or willing to be Homebrew maintainers but have shown continued involvement in the Homebrew community may be admitted by a majority vote of the [Project Leadership Committee](Homebrew-Governance.md#4-project-leadership-committee).
When admitted as members:

6
docs/Prose-Style-Guidelines.md
View File

@ -1,5 +1,5 @@
---
last_review_date: "2025-02-08"
last_review_date: 2025-05-22
---
# Prose Style Guidelines
@ -23,7 +23,7 @@ Homebrew's audience includes users with a wide range of education and experience
We strive for "correct" but not "fancy" usage. Think newspaper article, not academic paper.
This is a set of guidelines to be applied using human judgement, not a set of hard and fast rules. It is like [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/rubocop-hq/ruby-style-guide#the-ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
This is a set of guidelines to be applied using human judgement, not a set of hard and fast rules. It is more like [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage) and less like the [Ruby Style Guide](https://github.com/rubocop-hq/ruby-style-guide#the-ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
The intent of this document is to help authors make decisions about clarity, style, and consistency. It is not to help settle arguments about who knows English better. Don't use this document to be a jerk.
@ -53,6 +53,8 @@ We prefer:
* Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments
* Prefer Markdown over other markup formats unless their specific features are needed
* GitHub Flavoured Markdown. GitHub's implementation is the standard, period.
* Link to other documentation pages with relative links to the Markdown filename rather than the full URL
* e.g. `FAQ.md` instead of `https://docs.brew.sh/FAQ`
### Typographical conventions

2
docs/Tips-and-Tricks.md
View File

@ -143,7 +143,7 @@ export HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK=1
export HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN="$(printf 'anonymous:' | base64)"
```
## Loading Homebrew from the same dotfiles on different operating systems
## Load Homebrew from the same dotfiles on different operating systems
Some users may want to use the same shell initialization files on macOS and Linux.
Use this to detect the likely Homebrew installation directory and load Homebrew when it's found.

4
docs/vale-styles/Homebrew/README.md
View File

@ -1,7 +1,7 @@
---
last_review_date: "1970-01-01"
last_review_date: 2025-05-22
---
# Vale Styles
Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html).
Based on Homebrew's [Prose Style Guidelines](/docs/Prose-Style-Guidelines.md).