gem-man 0.1.0 → 0.1.1

data/README.md

@@ -3,10 +3,11 @@ gem-man(1) -- view a gem's man page
 
 ## SYNOPSIS
 
-`gem man` <GEM>  
-`gem man` --latest <GEM>  
-`gem man` --exact <GEM>  
-`gem man` --all
+    gem man <GEM>
+    gem man <SECTION> <GEM>
+    gem man --latest <GEM>
+    gem man --exact <GEM>
+    gem man --all
 
 ## DESCRIPTION
 
@@ -27,6 +28,14 @@ displayed.
 Man pages are any files whose extension is a single digit [0-9],
 e.g. `ron.1`.
 
+## SECTION
+
+Specifying a `SECTION` as the first argument narrows the search to man
+pages matching the provided section. For example, if the "mustache"
+gem includes `man/mustache.1` and `man/mustache.5` the command `gem
+man 1 mustache` will display `man/mustache.1` without asking if you'd
+like to see `man/mustache.5`.
+
 ## OPTIONS
 
 `gem man`'s default mode of operation is to open a man page for a
@@ -54,6 +63,12 @@ See `gem help man` to view the options at any time.
 
     gem install gem-man
 
+## EXAMPLES
+
+    gem man mustache
+    gem man 1 ron
+    gem man -a
+
 ## BUGS
 
 Requires the `man(1)` script to be in your path, executable, and to

data/lib/rubygems/commands/man_command.rb

@@ -25,6 +25,10 @@ class Gem::Commands::ManCommand < Gem::Command
     end
   end
 
+  def usage
+    "gem man [SECTION] GEMNAME"
+  end
+
   def add_latest_version_option
     add_option('-l', '--latest',
       'If there are multiple versions, open the latest') do |value, options|
@@ -39,28 +43,39 @@ class Gem::Commands::ManCommand < Gem::Command
   end
 
   def arguments
+    "SECTION       section of the manual to search\n" +
     "GEMNAME       gem whose manual you wish to read"
   end
 
   def execute
+    if get_one_optional_argument =~ /^\d$/
+      section = get_one_optional_argument
+    end
+
     if options[:all]
       puts "These gems have man pages:", ''
       Gem.source_index.gems.each do |name, spec|
         puts "#{spec.name} #{spec.version}" if spec.has_manpage?
       end
     else
-      # Grab our target gem.
-      name = get_one_gem_name
+      # gem man 1 mustache
+      section, name, _ = options[:args]
+
+      if name.nil?
+        # gem man mustache
+        name, section = section, nil
+      end
 
       # Try to read manpages.
-      read_manpage get_spec(name) { |s| s.has_manpage? }
+      read_manpage(get_spec(name), section)
     end
   end
 
-  def read_manpage(spec)
+  def read_manpage(spec, section = nil)
     return if spec.nil?
 
-    paths = spec.manpages
+    paths = spec.manpages(section)
+    return if paths.empty?
 
     # man/ron.1 => ron(1)
     names = paths.map do |path|

data/lib/rubygems/gem/specification.rb

@@ -1,13 +1,13 @@
 class Gem::Specification
   # Does this specification include a manpage?
-  def has_manpage?
-    manpages.any?
+  def has_manpage?(section = nil)
+    manpages(section).any?
   end
 
   # Paths to the manpages included in this gem.
-  def manpages
+  def manpages(section = nil)
     @files.select do |file|
-      file =~ /man\/(.+).\d$/
+      file =~ /man\/(.+).#{section || '\d'}$/
     end
   end
 end

data/man/gem-man.1

@@ -7,18 +7,16 @@
 \fBgem-man\fR \-\- view a gem's man page
 .
 .SH "SYNOPSIS"
-\fBgem man\fR \fIGEM\fR
 .
-.br
-\fBgem man\fR \-\-latest \fIGEM\fR
-.
-.br
-\fBgem man\fR \-\-exact \fIGEM\fR
-.
-.br
-\fBgem man\fR \-\-list
+.nf
+
+\fBgem man <GEM>
+gem man <SECTION> <GEM>
+gem man --latest <GEM>
+gem man --exact <GEM>
+gem man --all \fR
 .
-.br
+.fi
 .
 .SH "DESCRIPTION"
 The \fBgem man\fR command can be used to display a man page for an
@@ -38,6 +36,13 @@ displayed.
 Man pages are any files whose extension is a single digit [0\-9],
 e.g. \fBron.1\fR.
 .
+.SH "SECTION"
+Specifying a \fBSECTION\fR as the first argument narrows the search to man
+pages matching the provided section. For example, if the "mustache"
+gem includes \fBman/mustache.1\fR and \fBman/mustache.5\fR the command \fBgem
+man 1 mustache\fR will display \fBman/mustache.1\fR without asking if you'd
+like to see \fBman/mustache.5\fR.
+.
 .SH "OPTIONS"
 \fBgem man\fR's default mode of operation is to open a man page for a
 single gem or, if multiple man pages are found, ask which you'd like
@@ -74,6 +79,16 @@ See \fBgem help man\fR to view the options at any time.
 .
 .fi
 .
+.SH "EXAMPLES"
+.
+.nf
+
+\fBgem man mustache
+gem man 1 ron
+gem man -a \fR
+.
+.fi
+.
 .SH "BUGS"
 Requires the \fBman(1)\fR script to be in your path, executable, and to
 accept a full path to a manual.

data/man/gem-man.1.html

@@ -66,11 +66,12 @@
 <p><code>gem-man</code> -- view a gem's man page</p>
 <h2>SYNOPSIS</h2>
 
-<p><code>gem man</code> <var>GEM</var><br>
-<code>gem man</code> --latest <var>GEM</var><br>
-<code>gem man</code> --exact <var>GEM</var><br>
-<code>gem man</code> --list<br>
-</p>
+<pre><code>gem man &lt;GEM&gt;
+gem man &lt;SECTION&gt; &lt;GEM&gt;
+gem man --latest &lt;GEM&gt;
+gem man --exact &lt;GEM&gt;
+gem man --all
+</code></pre>
 
 <h2>DESCRIPTION</h2>
 
@@ -91,6 +92,14 @@ displayed.</p>
 <p>Man pages are any files whose extension is a single digit [0-9],
 e.g. <code>ron.1</code>.</p>
 
+<h2>SECTION</h2>
+
+<p>Specifying a <code>SECTION</code> as the first argument narrows the search to man
+pages matching the provided section. For example, if the "mustache"
+gem includes <code>man/mustache.1</code> and <code>man/mustache.5</code> the command <code>gem
+man 1 mustache</code> will display <code>man/mustache.1</code> without asking if you'd
+like to see <code>man/mustache.5</code>.</p>
+
 <h2>OPTIONS</h2>
 
 <p><code>gem man</code>'s default mode of operation is to open a man page for a
@@ -127,6 +136,13 @@ man</code> will ask which you'd prefer.</p>
 <pre><code>gem install gem-man
 </code></pre>
 
+<h2>EXAMPLES</h2>
+
+<pre><code>gem man mustache
+gem man 1 ron
+gem man -a
+</code></pre>
+
 <h2>BUGS</h2>
 
 <p>Requires the <code>man(1)</code> script to be in your path, executable, and to

data/man/gem-man.1.ron

@@ -3,10 +3,11 @@ gem-man(1) -- view a gem's man page
 
 ## SYNOPSIS
 
-`gem man` <GEM>  
-`gem man` --latest <GEM>  
-`gem man` --exact <GEM>  
-`gem man` --all
+    gem man <GEM>
+    gem man <SECTION> <GEM>
+    gem man --latest <GEM>
+    gem man --exact <GEM>
+    gem man --all
 
 ## DESCRIPTION
 
@@ -27,6 +28,14 @@ displayed.
 Man pages are any files whose extension is a single digit [0-9],
 e.g. `ron.1`.
 
+## SECTION
+
+Specifying a `SECTION` as the first argument narrows the search to man
+pages matching the provided section. For example, if the "mustache"
+gem includes `man/mustache.1` and `man/mustache.5` the command `gem
+man 1 mustache` will display `man/mustache.1` without asking if you'd
+like to see `man/mustache.5`.
+
 ## OPTIONS
 
 `gem man`'s default mode of operation is to open a man page for a
@@ -54,6 +63,12 @@ See `gem help man` to view the options at any time.
 
     gem install gem-man
 
+## EXAMPLES
+
+    gem man mustache
+    gem man 1 ron
+    gem man -a
+
 ## BUGS
 
 Requires the `man(1)` script to be in your path, executable, and to

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: gem-man
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Chris Wanstrath