bitboxer / manpages

Gem to add man pages support to ruby gems

Manpages

This plugin will add man pages support to ruby gems. Instead of adding a new command like gem-man it will try to link the files to a place the man command automatically discovers.

With rvm and chruby it works out of the box, but sadly for rbenv we need to add hooks that modify the man symlink depending on the ruby version currently used.

Installation

gem install manpages && gem manpages --update-all

This plugin automatically hooks into the ruby gems system. Every gem installed afterwards is checked for manpages. If this gem finds them, it exposes them to the man command.

Using this with rbenv

Sadly rbenv uses shims to hide the actual executables. This makes it a bit harder to make this gem work in that environment.

This gem provides hooks to change the man path for the current used ruby version. To install them execute the following line:

curl -o- https://raw.githubusercontent.com/bitboxer/manpages/master/rbenv/rbenv_hook_install.sh | bash

After the hooks are installed, rbenv will always change the man symlink to the currently used ruby version. Sadly rbenv does not provide a hook that is fired when switching ruby versions. This means that the path can only be corrected when executing a command provided by a gem. If you want to have the correct man page for a gem, you need to execute the command of that gem, first.

How this works

After a gem is installed, this plugin will check for a directory called man within the gem and link the manpages it finds to BIN_DIR/../share/man, where BIN_DIR is the directory where the executable of the gem is installed.

Most man versions will automatically search this directory and no additional work is required. If you install a gem that includes a man page (e.g. guard), you can simply use man guard and you will see the man page the gem provided.

Providing man pages with your gem

The most common way in the ruby world to create a man page is through a tool called ronn. Ronn uses a modified variant of markdown as source file. More details about the format can be found here. In the newest version kramdown also is able to generate man pages.

Make sure the resulting manpage is in a folder called man in the root of the gem. Files stored in that directory will automatically be exposed to the man command.

Examples for gems with manpages are guard or gem-man.

manpages's Issues

chore: exclude Gemfile, Gemfile.lock from files that go into the gem

Using wrong directory to save man pages

Chore: In gemspec, replace git invocation with Dir[] + reject

The gemspec makes the target system rely on Git being installed. No need, really.

I noted this while looking at the gemspec, which has no runtime dependencies.

File.expand_path

hi!

You should be able to replace the File.join on line 8 and File.absolute_path(File.join(...)) on line 16 with File.expand_path

E.g.,

  target_dir = File.expand_path(installer.bin_dir, "../share/man")

and

  target_dir = File.expand_path(bin_dir, "../share/man")

Add rvm hook

For rvm we need to add a hook at each version change to manipulate the MANPATH environment variable to point to the correct version.

Find man pages and copy them

After a gem is installed, we need to find out if it has a man page (example in gem-man) and
copy the file to BIN_DIR/../share/man . We also need to create the directory structure inside of the share/man to match the section number of that man page ( share/man/man1 ... ) .

Flaky test because of running order of tests

In #36 @gettalong mentioned that the "handles permission problems gracefull" test fails on his system because of an run order problem. I will need to investigate this.

Add rubocop config from bundler

Add command that relinks all manpages of already installed gems

Can't set it up in ruby 2.3.2

I wanted to try this gem, but couldn't get it working.

$ ruby-install ruby 2.3.2
# ... lots of output
>>> Successfully installed ruby 2.3.2 into /home/deivid/.rubies/ruby-2.3.2

$ source ~/.profile

$ chruby 2.3.2

$ ruby --version
ruby 2.3.2p217 (2016-11-15 revision 56796) [x86_64-linux]

$ gem install manpages && gem manpages --update-all
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
Successfully installed manpages-0.5.1
1 gem installed
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
ERROR:  While executing gem ... (Gem::CommandLineError)
    Unknown command manpages

Maybe it needs a more recent rubygems?

$ gem --version
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
2.5.2

$ gem update --system
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
Updating rubygems-update
Fetching: rubygems-update-2.6.8.gem (100%)
Successfully installed rubygems-update-2.6.8
Installing RubyGems 2.6.8
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
RubyGems 2.6.8 installed
# ... ChangeLog here

$ gem uninstall manpages
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
Successfully uninstalled manpages-0.5.1

$ gem --version
2.6.8

$ gem install manpages && gem manpages --update-all
Fetching: manpages-0.5.1.gem (100%)
Successfully installed manpages-0.5.1
1 gem installed
Error loading RubyGems plugin "/home/deivid/.gem/ruby/2.3.2/gems/manpages-0.5.1/lib/rubygems_plugin.rb": cannot load such file -- rubygems/gem/specification (LoadError)
ERROR:  While executing gem ... (Gem::CommandLineError)
    Unknown command manpages

Same thing... :(

My gem env

RubyGems Environment:
  - RUBYGEMS VERSION: 2.6.8
  - RUBY VERSION: 2.3.2 (2016-11-15 patchlevel 217) [x86_64-linux]
  - INSTALLATION DIRECTORY: /home/deivid/.gem/ruby/2.3.2
  - USER INSTALLATION DIRECTORY: /home/deivid/.gem/ruby/2.3.0
  - RUBY EXECUTABLE: /home/deivid/.rubies/ruby-2.3.2/bin/ruby
  - EXECUTABLE DIRECTORY: /home/deivid/.gem/ruby/2.3.2/bin
  - SPEC CACHE DIRECTORY: /home/deivid/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /home/deivid/.rubies/ruby-2.3.2/etc
  - RUBYGEMS PLATFORMS:
    - ruby
    - x86_64-linux
  - GEM PATHS:
     - /home/deivid/.gem/ruby/2.3.2
     - /home/deivid/.rubies/ruby-2.3.2/lib/ruby/gems/2.3.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
     - "gem" => "--no-document"
  - REMOTE SOURCES:
     - https://rubygems.org/
  - SHELL PATH:
     - /home/deivid/.gem/ruby/2.3.2/bin
     - /home/deivid/.rubies/ruby-2.3.2/lib/ruby/gems/2.3.0/bin
     - /home/deivid/.rubies/ruby-2.3.2/bin
     - /usr/local/sbin
     - /usr/local/bin
     - /usr/sbin
     - /usr/bin
     - /sbin
     - /bin
     - /usr/games
     - /usr/local/games
     - /home/deivid/.cabal/bin
     - /usr/local/texlive/2015/bin/x86_64-linux
     - /home/deivid/.local/bin

Thanks!

remove register command, it is not needed anymore

Remove command class

Can't see man pages after installation

$ ruby --version
ruby 2.3.2p217 (2016-11-15 revision 56796) [x86_64-linux]

$ gem --version
2.6.8

$ gem list

*** LOCAL GEMS ***

bigdecimal (default: 1.2.8)
io-console (default: 0.4.5)
json (default: 1.8.3)
psych (default: 2.1.0)
rdoc (default: 4.2.1)

$ gem install manpages
Fetching: manpages-0.5.2.gem (100%)
Successfully installed manpages-0.5.2
1 gem installed

$ gem install gem-man
Fetching: gem-man-0.3.0.gem (100%)
Successfully installed gem-man-0.3.0
1 gem installed

$ man gem-man
No existe entrada de manual para gem-man

$ # mmmm, maybe it's not done on installation and I need to generate them?

$ gem manpages --update-all
Installing man pages for gem-man 0.3.0

$ # Nice, it looks like something good was done

$ man gem-man
No existe entrada de manual para gem-man

$ # But still can't see man pages, maybe it's something with my "man setup"?

Add description on how to add manpages to a gem

Add chruby hook

See https://github.com/postmodern/chruby/wiki/Implementing-an-'after-use'-hook

change test suite to rspec

Uninstall man pages

If a gem is uninstalled, remove the symlink if it is the version that is deleted now

Make sure to install only the latest version of the man page

If a gem is installed with multiple versions, make sure only the man page of the latest version is installed. This is the executable that by default is called by the rubygems system if not otherwise specified.

Do not crash if permissions don't allow creating of dirs/files

Do not overwrite man files

If a man file already exists, check if you need to overwrite it. We only overwrite symlinks that are already present and point to the gem directory.

Add rbenv hook

For rbenv we need to change the MANPATH environment variable and make it point to the correct directory. This is done using hooks in rbenv. Sadly rbenv does not override the
cd command. Because of that we only have the execute hook that will let us change the dir after/before a command is executed. Meaning the man page will be found after the command was run first.