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.

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

Docs: assorted refinements for output #15986

Merged

Conversation

EricFromCanada
Copy link
Member

@EricFromCanada EricFromCanada commented Sep 9, 2023

  • adds a paragraph to brew deps explaining the cases in which it'll be in runtime dependencies mode (xref The output of brew deps protobuf is different from brew deps protobuf --tree #13184)
  • fixes for rubydoc output formatting and linking
  • marks blocks of console output using the console highlighter
  • adds a HOMEBREW_API_WWW global and use it in the documentation
  • various formatting, grammar and wording fixes to documentation and comments

Copy link
Contributor

@apainintheneck apainintheneck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work as usual. I left some nits but I'm fine with merging this as is.

@@ -250,19 +250,18 @@ See the [Acceptable Casks documentation](Acceptable-Casks.md#finding-a-home-for-

Hop into your tap and check to make sure your new cask is there:

```bash
```console
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the advantage of using console here over bash or sh?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This lexer distinguishes between what's typed at a prompt and its output (example).

@@ -67,7 +67,7 @@ export HOMEBREW_INSTALL_BADGE="☕️ 🐸"

## Migrate a Homebrew installation to a new location

Run `brew bundle dump` and `brew bundle install` record an installation to and install from a `Brewfile`. See `brew bundle --help` for more details.
Running `brew bundle dump` and `brew bundle install` will record an installation to and install from a `Brewfile`. See `brew bundle --help` for more details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Running brew bundle dump will record an installation in a Brewfile while brew bundle install will install from a Brewfile.

IMO this would be clearer by splitting things up more like this.

@@ -11,13 +11,12 @@ def release_args
Homebrew::CLI::Parser.new do
description <<~EOS
Create a new draft Homebrew/brew release with the appropriate version number and release notes.
Requires write access to the Homebrew/brew repository.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it'd be better with Note: ....

@@ -333,7 +333,7 @@ module EnvConfig
boolean: true,
},
HOMEBREW_PIP_INDEX_URL: {
description: "If set, `brew install <formula>` will use this URL to download PyPI package resources.",
description: "If set, `brew install` <formula> will use this URL to download PyPI package resources.",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I prefer the old way more since it groups together the command with the arguments into one logical unit.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a quirk of the fact that the docs need to be processed by both a Markdown processor for web pages and ronn for manpages. This format is required because the original results in brew install *formula* on the webpage, rather than brew install formula (with "formula" in italics to indicate it's a placeholder word within a suggested command).

Copy link
Member

@MikeMcQuaid MikeMcQuaid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again @EricFromCanada!

@MikeMcQuaid MikeMcQuaid merged commit 4e0ec25 into Homebrew:master Sep 11, 2023
31 checks passed
@EricFromCanada EricFromCanada deleted the docs-assorted-improvements branch September 11, 2023 16:26
@github-actions github-actions bot added the outdated PR was locked due to age label Oct 13, 2023
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 13, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
outdated PR was locked due to age
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants