├── .gitignore ├── man ├── gem-man.1.ronn ├── gem-man.1 └── gem-man.1.html ├── lib ├── rubygems_plugin.rb └── rubygems │ ├── gem │ └── specification.rb │ └── commands │ └── man_command.rb ├── Rakefile ├── gem-man.gemspec ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | dist/* 2 | -------------------------------------------------------------------------------- /man/gem-man.1.ronn: -------------------------------------------------------------------------------- 1 | ../README.md -------------------------------------------------------------------------------- /lib/rubygems_plugin.rb: -------------------------------------------------------------------------------- 1 | require 'rubygems/command_manager' 2 | require 'rubygems/version_option' 3 | require 'rubygems/gem/specification' 4 | 5 | Gem::CommandManager.instance.register_command :man 6 | -------------------------------------------------------------------------------- /lib/rubygems/gem/specification.rb: -------------------------------------------------------------------------------- 1 | class Gem::Specification 2 | 3 | ## 4 | # Returns the full path to installed gem's manual directory. 5 | 6 | def man_dir 7 | @man_dir ||= File.join(respond_to?(:gem_dir) ? gem_dir : full_gem_path, 'man') 8 | end 9 | 10 | ## 11 | # Does this specification include a manpage? 12 | 13 | def has_manpage?(section = nil) 14 | File.directory?(man_dir) && manpages(section).any? 15 | end 16 | 17 | ## 18 | # Paths to the manpages included in this gem. 19 | 20 | def manpages(section = nil) 21 | Dir.entries(man_dir).select do |file| 22 | file =~ /(.+).#{section || '\d'}$/ 23 | end 24 | end 25 | end 26 | -------------------------------------------------------------------------------- /Rakefile: -------------------------------------------------------------------------------- 1 | desc "Build the manual" 2 | task :build_man do 3 | sh "ron -br5 --organization=DEFUNKT --manual='RubyGems Manual' man/*.ron" 4 | end 5 | 6 | desc "Show the manual" 7 | task :man => :build_man do 8 | exec "man man/gem-man.1" 9 | end 10 | 11 | begin 12 | require 'mg' 13 | MG.new('gem-man.gemspec') 14 | rescue LoadError 15 | warn "gem install mg to get gem tasks" 16 | end 17 | 18 | desc "Ship to GitHub pages" 19 | task :pages => :build_man do 20 | `rm -rf htmls` 21 | mkdir "htmls" 22 | `cp man/*.html htmls` 23 | `git checkout gh-pages` 24 | `mv htmls/* .` 25 | rm_rf "htmls" 26 | `mv gem-man.1.html index.html` 27 | `git add .` 28 | `git commit -m updated` 29 | `git push origin gh-pages` 30 | `git checkout master` 31 | puts :done 32 | end 33 | -------------------------------------------------------------------------------- /gem-man.gemspec: -------------------------------------------------------------------------------- 1 | Gem::Specification.new do |s| 2 | s.name = "gem-man" 3 | s.version = "0.3.0" 4 | s.date = "2011-08-15" 5 | s.summary = "View a gem's man page." 6 | s.homepage = "https://github.com/defunkt/gem-man" 7 | s.email = "chris@ozmm.org" 8 | s.authors = [ "Chris Wanstrath" ] 9 | 10 | s.files = Dir.glob("{bin,lib,man}/**/*") + %w( README.md Rakefile LICENSE ) 11 | 12 | s.description = < 14 | gem man
15 | gem man --latest 16 | gem man --exact 17 | gem man --all \fR 18 | . 19 | .fi 20 | . 21 | .SH "DESCRIPTION" 22 | The \fBgem man\fR command can be used to display a man page for an 23 | installed RubyGem. The man page must be included with the gem \- \fBgem-man\fR does no generation or magic. 24 | . 25 | .P 26 | For an introduction to man pages, see \fBman(1)\fR (or type \fBman man\fR in 27 | your shell). 28 | . 29 | .SH "QUICKSTART" 30 | . 31 | .nf 32 | 33 | \fBgem install gem-man 34 | gem man gem-man \fR 35 | . 36 | .fi 37 | . 38 | .P 39 | Metalicious. 40 | . 41 | .SH "GEM" 42 | \fBgem man\fR expects to be passed the name of an installed gem. If there 43 | are multiple man pages found for the gem, you will be asked which 44 | you'd like to view. If only a single man page is found it will be 45 | displayed. 46 | . 47 | .P 48 | Man pages are any files whose extension is a single digit [0\-9], 49 | e.g. \fBron.1\fR. 50 | . 51 | .SH "SECTION" 52 | Specifying a \fBSECTION\fR as the first argument narrows the search to man 53 | pages matching the provided section. For example, if the "mustache" 54 | gem includes \fBman/mustache.1\fR and \fBman/mustache.5\fR the command \fBgem 55 | man 1 mustache\fR will display \fBman/mustache.1\fR without asking if you'd 56 | like to see \fBman/mustache.5\fR. 57 | . 58 | .SH "OPTIONS" 59 | \fBgem man\fR's default mode of operation is to open a man page for a 60 | single gem or, if multiple man pages are found, ask which you'd like 61 | to open. If there are any ambiguities as to which gem to use, \fBgem 62 | man\fR will ask which you'd prefer. 63 | . 64 | .P 65 | You can specify gems or list available gems using a few options. 66 | . 67 | .TP 68 | \fB-l\fR, \fB--latest\fR 69 | If there are multiple versions of a gem, open the latest. 70 | . 71 | .TP 72 | \fB-v\fR, \fB--version\fR 73 | Specify version of gem to man. 74 | . 75 | .TP 76 | \fB-e\fR, \fB--exact\fR 77 | Only list exact matches. 78 | . 79 | .TP 80 | \fB-a\fR, \fB--all\fR 81 | List all installed gems that have manuals. 82 | . 83 | .P 84 | See \fBgem help man\fR to view the options at any time. 85 | . 86 | .SH "INSTALL" 87 | . 88 | .nf 89 | 90 | \fBgem install gem-man \fR 91 | . 92 | .fi 93 | . 94 | .SH "EXAMPLES" 95 | . 96 | .nf 97 | 98 | \fBgem man mustache 99 | gem man 1 ron 100 | gem man -a \fR 101 | . 102 | .fi 103 | . 104 | .SH "AUTHORING" 105 | For information on authoring man pages, see \fI\fBron(7)\fR\fR: 106 | . 107 | .IP "" 4 108 | . 109 | .nf 110 | 111 | \fBgem install ron 112 | gem man 7 ron \fR 113 | . 114 | .fi 115 | . 116 | .IP "" 0 117 | . 118 | .SH "BUGS" 119 | Requires the \fBman(1)\fR script to be in your path, executable, and to 120 | accept a full path to a manual. 121 | . 122 | .P 123 | Requires Ruby and RubyGems 1.3.2 (or higher). 124 | . 125 | .P 126 | Please report other bugs at \fIhttp://github.com/defunkt/gem\-man/issues\fR 127 | . 128 | .SH "THANKS" 129 | . 130 | .IP "\(bu" 4 131 | adamsanderson for open_gem 132 | . 133 | .IP "\(bu" 4 134 | rtomayko for ron 135 | . 136 | .IP "" 0 137 | . 138 | .SH "COPYRIGHT" 139 | gem\-man is Copyright (C) 2010 Chris Wanstrath with parts from Adam 140 | Sanderson. 141 | . 142 | .SH "SEE ALSO" 143 | ron(7), man(1), less(1), roff(7), groff(1),\fIhttp://en.wikipedia.org/wiki/Man_page\fR, \fIhttp://github.com/defunkt/gem\-man\fR 144 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | gem-man(1) -- view a gem's man page 2 | =================================== 3 | 4 | ## SYNOPSIS 5 | 6 | gem man 7 | gem man
8 | gem man --system 9 | gem man --latest 10 | gem man --exact 11 | gem man --all 12 | 13 | ## DESCRIPTION 14 | 15 | The `gem man` command can be used to display a man page for an 16 | installed RubyGem. The man page must be included with the gem - 17 | `gem-man` does no generation or magic. 18 | 19 | For an introduction to man pages, see `man(1)` (or type `man man` in 20 | your shell). 21 | 22 | ## QUICKSTART 23 | 24 | gem install gem-man 25 | gem man gem-man 26 | 27 | Metalicious. 28 | 29 | ## GEM 30 | 31 | `gem man` expects to be passed the name of an installed gem. If there 32 | are multiple man pages found for the gem, you will be asked which 33 | you'd like to view. If only a single man page is found it will be 34 | displayed. 35 | 36 | Man pages are any files whose extension is a single digit [0-9], 37 | e.g. `ronn.1`. 38 | 39 | ## SECTION 40 | 41 | Specifying a `SECTION` as the first argument narrows the search to man 42 | pages matching the provided section. For example, if the "mustache" 43 | gem includes `man/mustache.1` and `man/mustache.5` the command `gem 44 | man 1 mustache` will display `man/mustache.1` without asking if you'd 45 | like to see `man/mustache.5`. 46 | 47 | ## OPTIONS 48 | 49 | `gem man`'s default mode of operation is to open a man page for a 50 | single gem or, if multiple man pages are found, ask which you'd like 51 | to open. If there are any ambiguities as to which gem to use, `gem 52 | man` will ask which you'd prefer. 53 | 54 | You can specify gems or list available gems using a few options. 55 | 56 | * `-s`, `--system`: 57 | Fall back to searching for system manuals. That is, `gem man -s 58 | mac` will first look for a gem named `mac` with a man page before 59 | looking for any system man pages named `mac`. `gem man -s fork` 60 | should find the fork(2) manual, for instance. 61 | 62 | * `-l`, `--latest`: 63 | If there are multiple versions of a gem, open the latest. 64 | 65 | * `-v`, `--version`: 66 | Specify version of gem to man. 67 | 68 | * `-e`, `--exact`: 69 | Only list exact matches. 70 | 71 | * `-a`, `--all`: 72 | List all installed gems that have manuals. 73 | 74 | See `gem help man` to view the options at any time. 75 | 76 | ## INSTALL 77 | 78 | gem install gem-man 79 | 80 | ## EXAMPLES 81 | 82 | gem man mustache 83 | gem man 1 ronn 84 | gem man -a 85 | 86 | ## AUTHORING 87 | 88 | For information on authoring man pages, see [`ronn(7)`][r7]: 89 | 90 | gem install ronn 91 | gem man 7 ronn 92 | 93 | ## CHEATING 94 | 95 | If you want `man` to find RubyGems, it's this easy: 96 | 97 | alias man="gem man -s" 98 | 99 | Now: 100 | 101 | man say 102 | man rails 103 | man 1 ronn 104 | man 2 fork 105 | 106 | ## BUGS 107 | 108 | Requires the `man(1)` script to be in your path, executable, and to 109 | accept a full path to a manual. 110 | 111 | Requires Ruby and RubyGems 1.3.2 (or higher). 112 | 113 | Please report other bugs at 114 | 115 | ## THANKS 116 | 117 | * adamsanderson for open_gem 118 | * rtomayko for ronn 119 | 120 | ## COPYRIGHT 121 | 122 | gem-man is Copyright (C) 2010 Chris Wanstrath with parts from Adam 123 | Sanderson. 124 | 125 | ## SEE ALSO 126 | 127 | ronn(7), man(1), less(1), roff(7), groff(1), 128 | , 129 | 130 | 131 | [r7]: http://rtomayko.github.com/ronn/ 132 | -------------------------------------------------------------------------------- /lib/rubygems/commands/man_command.rb: -------------------------------------------------------------------------------- 1 | # Much of this is stolen from the `open_gem` RubyGem's "read" 2 | # command - thanks Adam! 3 | # 4 | # http://github.com/adamsanderson/open_gem/blob/dfddaa286e/lib/rubygems/commands/read_command.rb 5 | class Gem::Commands::ManCommand < Gem::Command 6 | include Gem::VersionOption 7 | 8 | def initialize 9 | super 'man', "Open a gem's manual", 10 | :command => nil, 11 | :version => Gem::Requirement.default, 12 | :latest => false, 13 | :all => false 14 | 15 | add_all_gems_option 16 | add_system_fallback_option 17 | add_latest_version_option 18 | add_version_option 19 | add_exact_match_option 20 | end 21 | 22 | def usage 23 | "gem man [SECTION] GEMNAME" 24 | end 25 | 26 | def arguments 27 | "SECTION section of the manual to search\n" + 28 | "GEMNAME gem whose manual you wish to read" 29 | end 30 | 31 | def add_all_gems_option 32 | add_option('-a', '--all', 33 | 'List all installed gems that have manuals.') do |value, options| 34 | options[:all] = true 35 | end 36 | end 37 | 38 | def add_system_fallback_option 39 | add_option('-s', '--system', 40 | 'Falls back to searching for system-wide man pages.') do |value, options| 41 | options[:system] = true 42 | end 43 | end 44 | 45 | def add_latest_version_option 46 | add_option('-l', '--latest', 47 | 'If there are multiple versions, open the latest') do |value, options| 48 | options[:latest] = true 49 | end 50 | end 51 | 52 | def add_exact_match_option 53 | add_option('-x', '--exact', 'Only list exact matches') do |value, options| 54 | options[:exact] = true 55 | end 56 | end 57 | 58 | def execute 59 | if get_one_optional_argument =~ /^\d$/ 60 | section = get_one_optional_argument 61 | end 62 | 63 | if options[:all] 64 | puts "These gems have man pages:", '' 65 | 66 | specs = Gem::Specification.respond_to?(:each) ? Gem::Specification : Gem.source_index.gems 67 | specs.each do |*name_and_spec| 68 | spec = name_and_spec.pop 69 | puts "#{spec.name} #{spec.version}" if spec.has_manpage? 70 | end 71 | else 72 | # gem man 1 mustache 73 | section, name, _ = options[:args] 74 | 75 | if name.nil? 76 | # gem man mustache 77 | name, section = section, nil 78 | end 79 | 80 | # Try to read manpages. 81 | if spec = get_spec(name) { |s| s.has_manpage?(section) } 82 | read_manpage(spec, section) 83 | elsif options[:system] 84 | exec "man #{section} #{name}" 85 | else 86 | abort "No manual entry for #{name}" 87 | end 88 | end 89 | end 90 | 91 | def read_manpage(spec, section = nil) 92 | return if spec.nil? 93 | 94 | paths = spec.manpages(section) 95 | return if paths.empty? 96 | 97 | # man/ron.1 => ron(1) 98 | names = paths.map do |path| 99 | path.sub(/.*\/(.+)\.(\d+)/, '\1(\2)') 100 | end 101 | 102 | if paths.size == 1 103 | manpath = paths[0] 104 | elsif paths.size > 1 105 | name, index = choose_from_list("View which manual?", names) 106 | manpath = paths[index] 107 | end 108 | 109 | if manpath 110 | exec "man #{File.join(spec.man_dir, manpath)}" 111 | else 112 | abort "no manuals found for #{spec.name}" 113 | end 114 | end 115 | 116 | def gem_path(spec) 117 | File.join(spec.installation_path, "gems", spec.full_name) 118 | end 119 | 120 | def get_spec(name, &block) 121 | # Since Gem::Dependency.new doesn't want a Regexp 122 | # We'll do it ourself! 123 | specs = if Gem::Specification.respond_to?(:each) 124 | Gem::Specification.each.select { |spec| name === spec.name } 125 | else 126 | Gem.source_index.search Gem::Dependency.new(name, options[:version]) 127 | end 128 | 129 | if block 130 | specs = specs.select { |spec| yield spec } 131 | end 132 | 133 | if specs.empty? 134 | # If we have not tried to do a pattern match yet, fall back on it. 135 | if !options[:exact] && !name.is_a?(Regexp) 136 | pattern = /#{Regexp.escape name}/ 137 | get_spec(pattern, &block) 138 | else 139 | nil 140 | end 141 | elsif specs.size == 1 || options[:latest] 142 | specs.last 143 | else 144 | choices = specs.map { |s| "#{s.name} #{s.version}" } 145 | c, i = choose_from_list "Open which gem?", choices 146 | specs[i] if i 147 | end 148 | end 149 | end 150 | -------------------------------------------------------------------------------- /man/gem-man.1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | gem-man(1) -- view a gem's man page 7 | 53 | 54 | 55 |
56 | 57 |

gem-man(1)

58 | 59 |
    60 |
  1. gem-man(1)
    2. 61 |
  2. RubyGems Manual
    3. 62 |
  3. gem-man(1)
    4. 63 |
64 | 65 |

NAME

66 |

gem-man -- view a gem's man page

67 |

SYNOPSIS

68 | 69 | 
gem man <GEM>
 70 | gem man <SECTION> <GEM>
 71 | gem man --latest <GEM>
 72 | gem man --exact <GEM>
 73 | gem man --all
 74 |
75 | 76 |

DESCRIPTION

77 | 78 |

The gem man command can be used to display a man page for an 79 | installed RubyGem. The man page must be included with the gem - 80 | gem-man does no generation or magic.

81 | 82 |

For an introduction to man pages, see man(1) (or type man man in 83 | your shell).

84 | 85 |

QUICKSTART

86 | 87 | 
gem install gem-man
 88 | gem man gem-man
 89 |
90 | 91 |

Metalicious.

92 | 93 |

GEM

94 | 95 |

gem man expects to be passed the name of an installed gem. If there 96 | are multiple man pages found for the gem, you will be asked which 97 | you'd like to view. If only a single man page is found it will be 98 | displayed.

99 | 100 |

Man pages are any files whose extension is a single digit [0-9], 101 | e.g. ron.1.

102 | 103 |

SECTION

104 | 105 |

Specifying a SECTION as the first argument narrows the search to man 106 | pages matching the provided section. For example, if the "mustache" 107 | gem includes man/mustache.1 and man/mustache.5 the command gem 108 | man 1 mustache will display man/mustache.1 without asking if you'd 109 | like to see man/mustache.5.

110 | 111 |

OPTIONS

112 | 113 |

gem man's default mode of operation is to open a man page for a 114 | single gem or, if multiple man pages are found, ask which you'd like 115 | to open. If there are any ambiguities as to which gem to use, gem 116 | man will ask which you'd prefer.

117 | 118 |

You can specify gems or list available gems using a few options.

119 | 120 |
121 |
122 | -l, --latest 123 |
124 |

If there are multiple versions of a gem, open the latest.

125 |
126 | -v, --version 127 |
128 |

Specify version of gem to man.

129 |
130 | -e, --exact 131 |
132 |

Only list exact matches.

133 |
134 | -a, --all 135 |
136 |

List all installed gems that have manuals.

137 |
138 | 139 | 140 |

See gem help man to view the options at any time.

141 | 142 |

INSTALL

143 | 144 | 
gem install gem-man
145 |
146 | 147 |

EXAMPLES

148 | 149 | 
gem man mustache
150 | gem man 1 ron
151 | gem man -a
152 |
153 | 154 |

AUTHORING

155 | 156 |

For information on authoring man pages, see ron(7):

157 | 158 | 
gem install ron
159 | gem man 7 ron
160 |
161 | 162 |

BUGS

163 | 164 |

Requires the man(1) script to be in your path, executable, and to 165 | accept a full path to a manual.

166 | 167 |

Requires Ruby and RubyGems 1.3.2 (or higher).

168 | 169 |

Please report other bugs at http://github.com/defunkt/gem-man/issues

170 | 171 |

THANKS

172 | 173 |
    174 |
  • adamsanderson for open_gem
    • 175 |
  • rtomayko for ron
    • 176 |
177 | 178 | 179 |

COPYRIGHT

180 | 181 |

gem-man is Copyright (C) 2010 Chris Wanstrath with parts from Adam 182 | Sanderson.

183 | 184 |

SEE ALSO

185 | 186 |

ron(7), man(1), less(1), roff(7), groff(1), 187 | http://en.wikipedia.org/wiki/Man_page, 188 | http://github.com/defunkt/gem-man

189 | 190 |
    191 |
  1. DEFUNKT
    2. 192 |
  2. March 2010
    3. 193 |
  3. gem-man(1)
    4. 194 |
195 | 196 |
197 | 198 | 199 | --------------------------------------------------------------------------------