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.

Sign up for GitHub

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

Jump to bottom

brew docs as an alias for open https://docs.brew.sh #13834

Closed
jmfayard opened this issue Sep 9, 2022 · 7 comments · Fixed by #13844
Closed

brew docs as an alias for open https://docs.brew.sh #13834

jmfayard opened this issue Sep 9, 2022 · 7 comments · Fixed by #13844
Labels
features New features help wanted We want help addressing this outdated PR was locked due to age

Comments

@jmfayard
Copy link

jmfayard commented Sep 9, 2022 •
edited

Provide a detailed description of the proposed feature

brew docs as a shortcut for open https://docs.brew.sh

Also udpate brew help

$ brew help
(....)
Further help:
  brew commands
  brew help [COMMAND]
  man brew
-  https://docs.brew.sh
+ brew docs

What is the motivation for the feature?

Laziness is one of the three great virtues of the programmer, as defined by Larry Wall.

Laziness is the quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it.

How will the feature be relevant to at least 90% of Homebrew users?

Benefits for users

It makes it marginally easier to 90% of Homebrew users to access the docs at https://docs.brew.sh

And maybe find the information they need, which is nice.

Benefits for maintainers

It is marginally nicer for Homebrew maintainers that Homebrew users are empowered to find the documentation they need. They would have to repeat themselves marginally less.

Of course, many users still won't read the docs, but now maintainers can reply

This is documented in $ brew docs, section Common Issues

This kind of reply makes it marginally more likely that users read the docs next time.
Yes it's just a RTFM, but I think/hope it's an empowering "Read the Friendly Manual" RTFM, not the "Read the Fucking Manual" RTFM.

Benefits for documentation writers

As someone who writes technical documentation myself, I know this is hard work and I know that I like it when more users actually use and benefit from the documentation.

What alternatives to the feature have been considered?

Bookmarking https://docs.brew.sh

But I'm too lazy to bookmark things and use browser bookmarks correctly.
@jmfayard jmfayard added the features New features label Sep 9, 2022
@carlocab
Copy link
Member

carlocab commented Sep 9, 2022

I'm open to a brew docs command, but I'd probably still keep https://docs.brew.sh in brew help for the benefit of users who are too lazy to type another command, and want to click on a URL instead.

@MikeMcQuaid
Copy link
Member

I love, admire and agree with the honest admission of laziness here. Given how little code would be required to implement this: would definitely review a PR.

@MikeMcQuaid MikeMcQuaid added the help wanted We want help addressing this label Sep 9, 2022
@RandomDSdevel
Copy link
Contributor

     These may well not be blocking comments regarding an initial implementation, as these could also be potential future extensions to an initial minimum viable product, but I have a few additional thoughts on some things to keep in mind for this kind of functionality:

  • Some users might want a '--browse'/'--no-browse' (in Homebrew 'CLI::Parser' parlance, which I'll use from here on to keep things shorter, '--[no-]browse') to control whether the command actually opens the destination URL in their browser or simply just prints the URL to their terminal as output.
  • All the documentation displayed on https://docs.brew.sh/ is available in users' local installation of Homebrew in '"$(brew --prefix)/docs";' it could (additionally) get rendered to output displayable as 'man' pages.
    • (An additional alternative would be to have invoking the new command spin a local web server up to display the documentation pages, but that would likely be better implemented as an external command.)
  • Finally, 'brew help' already exists; does 'brew docs' have to be a separate command? Git handles this by having 'git help' also provide access to 'man' pages that aren't documentation for individual sub-commands.

@jmfayard
Copy link
Author

jmfayard commented Sep 10, 2022 •
edited

Thanks for the feedback.

I also wondered, since I have never used linuxbrew, whether Linux, which uses a different command, should be supported as well?

Meaning whether it should be the Ruby equivalent of

xdg-open https://docs.brew.sh/ || open https://docs.brew.sh/

Reference: https://linux.die.net/man/1/xdg-open

@jonchang
Copy link
Contributor

utils.rb has exec_browser which commands like brew home use.

@RandomDSdevel
Copy link
Contributor

     As the maintainers would mention/point out, Linuxbrew got merged into Homebrew proper a while back (see Linuxbrew/brew#612, #7028, and the v1.9.0 and v3.3.0 release blog posts for some of the historical details.)

troymccabe added a commit to troymccabe/brew that referenced this issue Sep 12, 2022
@troymccabe
Adds brew docs to close Homebrew#13834
ac9a968
@troymccabe troymccabe mentioned this issue Sep 12, 2022
Merged
7 tasks
@troymccabe
Copy link
Contributor

Additional thoughts for add-ons:

--list: List all files matching "*.md" (except "README") in $(brew --repo)/docs. Optionally numerically indexed for:
--doc: Either the numeric index or name of a doc in --list. Opens that particular doc.

MikeMcQuaid added a commit that referenced this issue Sep 12, 2022
@MikeMcQuaid
Merge pull request #13844 from troymccabe/feature/13834-brew-docs-cmd
c7bd51b 
Adds `brew docs` to close #13834
@github-actions github-actions bot added the outdated PR was locked due to age label Oct 13, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 13, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
features New features help wanted We want help addressing this outdated PR was locked due to age
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Adds brew docs to close #13834 troymccabe/brew
6 participants
@MikeMcQuaid @jonchang @jmfayard @troymccabe @RandomDSdevel @carlocab