How to modify formula to link a man page

[jimtut]

I was looking for the docs for streamlink, so the first thing I tried was man streamlink, but no results were found. I tried other formulae, and their man pages worked (and I can see them in /opt/homebrew/share/man).

If I type brew list streamlink, I get:
/opt/homebrew/Cellar/streamlink/2.1.1/bin/streamlink
/opt/homebrew/Cellar/streamlink/2.1.1/libexec/bin/ (13 files)
/opt/homebrew/Cellar/streamlink/2.1.1/libexec/lib/ (1321 files)
/opt/homebrew/Cellar/streamlink/2.1.1/libexec/share/man/man1/streamlink.1
/opt/homebrew/Cellar/streamlink/2.1.1/libexec/pyvenv.cfg

So, there actually is a man (man1) page. Why isn't it installed/linked properly? I can't see anything in ANY formulae that has a specific step to link a man page.

How does that "magic" occur, and how do I get it to happen for formulae like streamlink that aren't doing it?

[carlocab]

The problem is that the formula's man directory is installed into libexec/share, but it should be installed into #{prefix}/share. You can open a pull request to fix it. Details on how to do so can be found in the docs, or in other formulae that specify the installation of manpages.

If you haven't yet, please read https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request before opening your PR.

[carlocab]

That's the magic of virtualenv_install_with_resources.

You probably just want to install a symlink in man1 to the streamlink.1 manpage in libexec.

[carlocab]

I get the idea

Great, but skim through the guide anyway so you're familiar with homebrew/core style regarding commit messages. (Though looking at the open PRs should also give you an idea.)

[SMillerDev]

virtualenv_install_with_resources will install to libexec by default so you'll have to link libexec/share to prefix/share

[jimtut]

SMillerDev, do you mean to just manually symlink on my Mac? That will break if/when streamlink upgrades though. Or, do you mean to change the formula so that a symlink is created inside the Cellar?

I'm assuming there's some brew-level magic going on too, such that if a man file is detected in the Cellar's share/man it gets symlinked into /opt/homebrew/share/man.

[carlocab]

I'm assuming there's some brew-level magic going on too, such that if a man file is detected in the Cellar's share/man it gets symlinked into /opt/homebrew/share/man.

This is correct.

[jimtut]

Looks like I could just copy/modify this line from https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/itstool.rb#L34:

  def install
    ...
    man1.install_symlink libexec/"share/man/man1/itstool.1"
  end

and apply this to the streamlink formula. Does that sound like the right approach? And that brew-magic I'm surmising exists will detect it in the Cellar's share/man and symlink it up into /opt/homebrew/share?

[carlocab]

Yep. Bump the formula's revision so that other users get the updated version of the formula when they do brew upgrade.

[jimtut]

Homebrew/homebrew-core#73992

[jimtut]

Yep. Bump the formula's revision so that other users get the updated version of the formula when they do brew upgrade.

I bumped the version from 2.1.1 to 2.1.2, in the commit message, according to https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request.

But, is that the version of the formula, or the version of the source code? I see that this particular formula references the URL of https://files.pythonhosted.org/packages/05/da/5f25244ae3fbfdc712fea9bb4d3a158b365a8d8240f2949b2b0bf411cddb/streamlink-2.1.1.tar.gz, which leads me to believe that 2.1.1 was the source code version, not the formula version?