rdoc_osx_dictionary 1.2.0 → 1.3.0

data/History.txt

@@ -1,3 +1,16 @@
+=== 1.3.0 / 2010-02-09
+
+* 4 minor enhancements:
+
+  * Improved hyperlinks in class definitions to point straight at methods.
+  * Improved method signature output (imajes)
+  * Made method signature a pre block to improve display of space formatted text.
+  * Refactored and improved class output to clearly define class extensions.
+
+* 1 bug fix:
+
+  * Specify exactly which ruby to execute (hinegardner)
+
 === 1.2.0 / 2010-02-03
 
 * 3 minor enhancements:

data/README.txt

@@ -7,6 +7,8 @@
 rdoc via Apple's Dictionary.app. Automatically builds and installs an
 Apple Dictionary with all rdoc nicely formatted.
 
+Inspired by: http://priithaamer.com/blog/ruby-on-rails-dictionary-for-macosx
+
 == FEATURES/PROBLEMS:
 
 * Automatically builds and installs an Apple Dictionary with all rdoc

data/bin/rdoc_osx_dictionary

@@ -1,4 +1,4 @@
-#!/usr/bin/ruby -ws
+#!/usr/bin/env ruby -ws
 
 $v ||= false
 $f ||= false

data/lib/rdoc_osx_dictionary.rb

@@ -3,20 +3,21 @@
 require 'fileutils'
 require 'rdoc/ri/driver'
 
+$q ||= false
+
 # Forces /bin/tr to ignore badly formatted "unicode". (no clue where from)
 ENV['LANG'] = ""
 ENV['LC_ALL'] = "C"
 
 class RDoc::OSXDictionary
-  VERSION = '1.2.0'
-
-  exclude = %w[ StringScanner#pre_match
-                StringScanner#post_match
-                Gem::Package::TarInput
-                IRB::OutputMethod
-              ]
+  VERSION = '1.3.0'
 
-  EXCLUDE = Hash[*exclude.map { |k| [k, true] }.flatten]
+  EXCLUDE = {
+    "StringScanner#pre_match"  => true,
+    "StringScanner#post_match" => true,
+    "Gem::Package::TarInput"   => true,
+    "IRB::OutputMethod"        => true,
+  }
 
   NAME_MAP = {
     '!'   => 'bang',
@@ -55,75 +56,108 @@ class RDoc::OSXDictionary
                             }.reverse.join("|"))
 
 
+  def id *args
+    args.map { |s| s.gsub(/:/, ',') }.join(",").gsub(/#{NAME_MAP_RE}/) { |x|
+      ",#{NAME_MAP[x]}"
+    }
+  end
+
   def display_class_info definition
     name       = definition["name"]
     fullname   = definition["full_name"]
     supername  = definition["superclass"]
-    includes   = (definition["includes"]||[]).join(", ")
-    classmeths = definition["class_methods"].map { |hash| hash["name"] }
-    instmeths  = definition["instance_methods"].map { |hash| hash["name"] }
     type       = supername ? "class" : "module"
     title      = supername ? "class #{fullname} < #{supername}" : "module #{fullname}"
     comment    = Array(definition["comment"]).join("\n")
-    constants  = Array(definition["constants"])
-    sources    = definition["sources"].map { |path|
-      next if path =~ /^.System/
-      path.sub(%r%^.*?1\.[89]/doc/([^/]+).*%, '\1')
-    }.compact
 
-    comment = "Improperly formatted" if EXCLUDE[fullname]
+    definition["includes"].map!  { |c| c["name"] }
+    definition["constants"].map! { |c| c["name"] }
 
-    id = "#{type}_#{fullname}".munge.gsub(/[\s:.#]/, '_')
+    return if $q and fullname !~ /^(String|Array|Bignum)/
+
+    comment = "Improperly formatted" if EXCLUDE[fullname]
 
     result = []
 
     shortname = "<d:index d:value=#{name.munge.inspect}/>" if name != fullname
 
     result << <<-"EOD".gsub(/^    /, '')
-    <d:entry id="#{id}" d:title="#{fullname}">
+    <d:entry id="#{id type, fullname}" d:title="#{fullname}">
       <d:index d:value="#{fullname.munge}"/>
       #{shortname}
       <h1>#{title.munge}</h1>
 
       #{comment}
-  EOD
+    EOD
+
+    extensions = []
+
+    definition["sources"].shift # remove first one as the original source
+    definition["sources"].each do |path|
+      next if path =~ /^.System/
+
+      gemname   = File.basename(path.sub(%r(/ri/\w+/cdesc-\w+.yaml), ''))
+      extension = YAML.load File.read(path).gsub(/- !.+/, '-')
+
+      extension["includes"].map!  { |c| c["name"] }
+      extension["constants"].map! { |c| c["name"] }
 
-    constants.map! { |c| c["name"] }
-
-    ext, ext_type = sources.size == 1 ? ["From", :str] : ["Extensions", :list]
-
-    [["Includes",         includes.munge,              :str],
-     ["Constants",        constants.join(", "),        :str],
-     ["Class Methods",    classmeths.join(", ").munge, :str],
-     ["Instance Methods", instmeths.join(", ").munge,  :str],
-     [ext, sources, ext_type]].each do |n, s, t|
-      next if s.empty?
-      case t
-      when :str then
-        result << "<h3>#{n}:</h3><p>#{s}</p>"
-      when :list then
-        items = s.map { |o| "<li>#{o}</li>" }.join("\n")
-        result << "<h3>#{n}:</h3><ul>#{items}</ul>"
-      else
-        raise "unknown type #{t.inspect}"
+      detail = class_details(name, fullname, extension, 4)
+
+      next if detail.empty?
+
+      extensions << "<h3>#{gemname}:</h3>"
+      extensions << detail
+      %w(class_methods instance_methods includes constants).each do |k|
+        definition[k] -= extension[k]
       end
     end
 
-    %w(name comment superclass includes constants class_methods
-     instance_methods sources display_name full_name).each do |key|
-      definition.delete key
-    end
+    result << class_details(name, fullname, definition)
+    result << "<h2>Extensions:</h2>" unless extensions.empty?
+    result << extensions
 
     result << <<-"EOD".gsub(/^    /, '')
     </d:entry>
-  EOD
+    EOD
     result.join("\n")
   end
 
+  def class_details name, fullname, definition, level = 2
+    h = "h#{level}"
+    result     = []
+    includes   = definition["includes"]
+    constants  = definition["constants"]
+
+    classmeths = definition["class_methods"].map { |hash|
+      name = hash["name"]
+      "<a href=\"x-dictionary:r:#{id "defs", fullname, name}\">#{name}</a>"
+    }
+
+    instmeths  = definition["instance_methods"].map { |hash|
+      name = hash["name"]
+      "<a href=\"x-dictionary:r:#{id "def", fullname, name}\">#{name.munge}</a>"
+    }
+
+    [["Includes",         includes],
+     ["Constants",        constants],
+     ["Class Methods",    classmeths],
+     ["Instance Methods", instmeths],
+    ].each do |n, a|
+      next if a.empty?
+
+      result << "<#{h}>#{n}:</#{h}><p>#{a.join ", "}</p>"
+    end
+
+    result
+  end
+
   def display_method_info definition
     fullname = definition["full_name"]
+    klass = definition["class"]
     name = definition["name"]
-    id = fullname.gsub(/#{NAME_MAP_RE}/) { |x| "_#{NAME_MAP[x]}" }
+
+    return if $q and klass !~ /^(String|Array|Bignum)/
 
     return if name =~ /_reduce_\d+/
 
@@ -133,19 +167,32 @@ class RDoc::OSXDictionary
 
     comment = "Improperly formatted" if EXCLUDE[fullname]
 
+    type = definition["is_singleton"] ? "defs" : "def"
+
+    # TODO: aliases don't have recv
+    # TODO: some regular methods don't have recv
+
     result = <<-"EOD".gsub(/^    /, '')
-    <d:entry id="def_#{id}" d:title="#{id}">
+    <d:entry id="#{id type, klass, name}" d:title="#{fullname.munge}">
       <d:index d:value="#{fullname.munge}"/>
       <d:index d:value="#{name.munge}"/>
       <h1>#{fullname.munge}</h1>
-      <p class="signatures">
-        <b>#{name.munge}#{params.munge}</b>
-      </p>
+      <pre class="signatures">
+        #{d_signatures(name, params)}
+      </pre>
       #{comment}
     </d:entry>
   EOD
   end
 
+  def d_signatures name, params
+    result = " "
+    if params.strip =~ /^\(/
+      result << "<b>#{name.munge}</b>"
+    end
+    result << "<b>#{params.munge.gsub(/\n/, "<br />")}</b>"
+  end
+
   def d_header
     result = <<-"EOD"
 <?xml version="1.0" encoding="UTF-8"?>
@@ -225,6 +272,7 @@ class RDoc::OSXDictionary
           result << d_entry(klass, dict[klass], true)
 
           methods.each do |k,v|
+            v["class"] = klass
             result << d_entry(k, v)
           end
 
@@ -291,7 +339,8 @@ class RDoc::OSXDictionary
   def self.install_gem_hooks
     return if @hooked[:hook]
 
-    cmd = File.expand_path File.join(__FILE__, "../../bin/rdoc_osx_dictionary")
+    rdoc_osx_dictionary_path = File.expand_path File.join(__FILE__, "../../bin/rdoc_osx_dictionary")
+    cmd = "#{Gem.ruby} #{rdoc_osx_dictionary_path}"
 
     # post_install isn't actually fully post-install... so I must
     # force via at_exit :(
@@ -321,7 +370,7 @@ end
 
 class String
   def munge
-    self.gsub(/&/, '&amp;').gsub(/>/, '&gt;').gsub(/</, '&lt;').gsub(/-/, 'minus')
+    self.gsub(/&/, '&amp;').gsub(/>/, '&gt;').gsub(/</, '&lt;').gsub(/-/, '&#45;')
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rdoc_osx_dictionary
 version: !ruby/object:Gem::Version 
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors: 
 - Ryan Davis
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-03 00:00:00 -08:00
+date: 2010-02-09 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -65,6 +65,8 @@ dependencies:
 description: |-
   rdoc via Apple's Dictionary.app. Automatically builds and installs an
   Apple Dictionary with all rdoc nicely formatted.
+  
+  Inspired by: http://priithaamer.com/blog/ruby-on-rails-dictionary-for-macosx
 email: 
 - ryand-ruby@zenspider.com
 executables: