rtfm 0.5.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Edgar
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,97 @@
+# rtfm
+
+Using RTFM, you can declaratively create nice, standard man pages for your
+Ruby projects using a slick, maintainable DSL. It also includes rake tasks
+to aid in debugging, generating, and installing your man files.
+
+## Normal manfiles are... interesting
+
+You might say: "but wait, aren't man pages already written in a DSL?", and you'd
+be right! However, here's an example of it:
+
+    .It Fl p
+    Acts mostly same as -n switch, but print the value of variable
+    .Li "$_"
+    at the each end of the loop.  For example:
+    .Bd -literal -offset indent
+    % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
+    MATZ
+    .Ed
+    .Pp
+    .It Fl r Ar library
+    Causes Ruby to load the library using require.  It is useful when using
+    .Fl n
+    or
+    .Fl p .
+
+That's from the Ruby manfile. This is using the `groff` macro language,
+which is awfully spiffy. However, it makes man files extremely tedious to
+maintain. It even spits out errors if you put a blank line in your manfile!
+
+## A word of caution
+
+Now, manfiles are long and complex, and contain a lot of information. Chances
+are, your RTFM-based manfile isn't actually going to be too much shorter than
+your normal groff-based entry. The difference is that by using the RTFM
+DSL, it should be very, very simple to maintain. Which is a huge
+win for your users.
+
+## Example Manual Page:
+
+    RTFM::ManPage.new("testing", 2) do |page|
+      page.summary = "testing man page"
+      page.option :verbose, "The verbose flag does a lot of stuff."
+      page.option :silliness, "Set how silly the application should be.", :argument => "n"
+      page.option :input, "The input flag takes a filename", :argument => "<input>"
+      
+      page.description do |desc|
+        desc.body = "This is a small, temporary description of the testing " +
+                    "man page."
+      end
+      page.see_also do |also|
+        also.reference "rails", 1
+        also.reference "ruby"
+      end
+      page.bugs = "There are a few bugs, but nothing too serious."
+      page.history = "This program has a storied history that I am too " +
+                     "lazy to include here."
+      page.authors do |authors|
+        authors.add "Michael Edgar", "adgar@carboni.ca"
+      end
+    end
+
+## Other wins
+
+The weird thing about making manfiles is that each section has its own semantics -
+sometimes, macros even change their meanings slightly. There are idioms and "best practices"
+for each. The cool part of RTFM is that we can try to match the idioms for you - you
+just provide the information we need.
+
+An example: in the "SEE ALSO" section, you can provide a list of other manual pages
+that are related to yours. In the example above, you see a couple of simple references.
+If you read the deep, dark documentation on the subject, you'll know that these references
+should be sorted by manual section, and then alphabetically within sections. RTFM will do that 
+for you. It's the little things that count.
+
+## Upcoming
+
+Hopefully we can get some of this integrated into RubyGems, though that's a long shot - 
+it's a long-standing, cross-platform project. But it's nice to dream.
+
+I hope to add the ability to insert raw groff if you are an advanced user and want some
+really spiffy formatting.
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+   bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Michael Edgar. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rtfm"
+    gem.summary = "Create makefiles declaratively. Comes with rake tasks."
+    gem.description = <<-EOF
+Using RTFM, you can declaratively create nice, standard man pages for your 
+Ruby projects using a slick, maintainable DSL. It also includes rake tasks 
+to aid in debugging, generating, and installing your man files.
+EOF
+    gem.email = "michael.j.edgar@dartmouth.edu"
+    gem.homepage = "http://github.com/michaeledgar/rtfm"
+    gem.authors = ["Michael Edgar"]
+    gem.add_development_dependency "bacon", ">= 0"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end
+
+$:.unshift File.expand_path(File.join(File.dirname(__FILE__), "lib"))
+require 'rtfm'
+require 'rtfm/tasks'
+
+RTFM::ManPage.new("testing", 2) do |page|
+  page.summary = "testing man page"
+  page.option :r, "Some r flag"
+  page.option :j, "Some j flag"
+  page.option :k, "Some k flag"
+  page.option :"0", "Some zero flag"
+  page.option :A, "Some capitalized flag"
+  page.option :Z, "some big-z flag"
+  page.option :verbose, "The verbose flag does a lot of stuff."
+  page.option :silliness, "Set how silly the application should be.", :argument => "n"
+  page.option :input, "The input flag takes a filename", :argument => "<input>"
+  
+  page.description do |desc|
+    desc.body = "This is a small, temporary description of the testing " +
+                "man page."
+  end
+  page.see_also do |also|
+    also.reference "rails", 1
+    also.reference "ruby"
+  end
+  page.bugs = "There are a few bugs, but nothing too serious."
+  page.history = "This program has a storied history that I am too " +
+                 "lazy to include here."
+  page.authors do |section|
+    section.author "Michael Edgar", "adgar@carboni.ca"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/lib/rtfm.rb

@@ -0,0 +1,20 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+if RUBY_VERSION < "1.9"
+  class String
+    unless method_defined?(:ord)
+      def ord
+        self[0]
+      end
+    end
+  end
+end
+
+require 'rtfm/groffstring'
+require 'rtfm/option'
+
+Dir[File.expand_path(File.join(File.dirname(__FILE__), "rtfm", "sections", "**"))].each do |f|
+  require f
+end
+
+require 'rtfm/manpage'

data/lib/rtfm/groffstring.rb

@@ -0,0 +1,45 @@
+module RTFM
+  class GroffString
+    
+    attr_reader :source
+    
+    def self.groffify(str = "")
+      out = self.new(str)
+      yield out
+      out.to_s
+    end
+    
+    def initialize(str = "")
+      @source = str.dup
+    end
+    
+    def to_s
+      source
+    end
+    
+    def rstrip
+      source.rstrip
+    end
+    
+    def add_line(line)
+      source << line.rstrip << "\n"
+    end
+    alias_method :<<, :add_line
+    
+    def section(section)
+      self.Sh section.upcase
+    end
+    
+    def put_name
+      self.Nm
+    end
+    
+    def reference(page, section = nil)
+      self.Xr page, (section || "")
+    end
+    
+    def method_missing(meth, *args, &block)
+      add_line ".#{meth} #{args.join(" ")}"
+    end
+  end
+end

data/lib/rtfm/manpage.rb

@@ -0,0 +1,71 @@
+module RTFM
+  class ManPage < Struct.new(:name, :section, :date, :summary)
+    class << self
+      def text_section(*args)
+        args.each do |sect|
+          class_eval %Q{
+            def #{sect}
+              @#{sect} ||= TextSection.new(:#{sect}, "")
+            end
+            def #{sect}=(str)
+              @#{sect} = TextSection.new(:#{sect}, str)
+            end
+          }
+        end
+      end
+      alias_method :text_sections, :text_section
+      
+      def add_section(name, klass)
+        klass = klass.to_s.intern
+        class_eval %Q{
+          def #{name}
+            @#{name} ||= #{klass}.new
+            yield @#{name} if block_given?
+            @#{name}
+          end
+        }
+      end
+      
+      def all_pages
+        @pages ||= []
+      end
+    end
+    
+    text_section :bugs, :diagnostics, :compatibility, :standards, :history
+    add_section :see_also, SeeAlsoSection
+    add_section :description, DescriptionSection
+    add_section :authors, AuthorsSection
+    add_section :synopsis, SynopsisSection
+    
+    def initialize(name, section=nil)
+      self.class.all_pages << self
+      self.name, self.section = name, section
+      self.date = DateTime.now
+      yield self
+    end
+
+    def add_option(name, desc, opts={})
+      opt = Option.new(name, desc, opts)
+      description.add_option opt
+      unless opts.has_key?(:synopsis) && !opts.delete(:synopsis)
+        synopsis.add_option(opt)
+      end
+    end
+    alias_method :option, :add_option
+    
+    def to_groff
+      GroffString.groffify do |out|
+        out.Dd date.strftime("%B %d, %Y")
+        out.Os
+        out.Dt name, (section || "")
+        out.section "NAME"
+        out.Nm name
+        out.Nd summary
+        [@synopsis, @description, @see_also, @history, @authors, @bugs].each do |sect|
+          out << sect.to_groff if sect
+        end
+      end
+    end
+  end
+  
+end

data/lib/rtfm/option.rb

@@ -0,0 +1,37 @@
+module RTFM
+  class Option < Struct.new(:title, :desc, :opts)
+    def title
+      super.to_s
+    end
+        
+    def argument
+      opts && (opts[:argument] || opts[:arg])
+    end
+    
+    def to_groff(how)
+      GroffString.groffify do |out|
+        args = [:Fl, self.title]
+        
+        if self.argument
+          argument = self.argument.to_s
+          if argument[0,1] == "<" && argument[-1,1] == ">"
+            args << "Ao" << argument[1..-2] << "Ac"
+          elsif argument[0,1] == "[" && argument[-1,1] == "]"
+            args << "Oo" << argument[1..-2] << "Oc"
+          else
+            args << :Ar << argument
+          end
+        end
+        
+        case how
+        when :option
+          out.Op *args
+        when :item
+          out.Pp
+          out.It *args
+          out << self.desc
+        end
+      end
+    end
+  end
+end

data/lib/rtfm/sections/authors.rb

@@ -0,0 +1,25 @@
+module RTFM
+  class AuthorsSection
+    def initialize
+      @authors = []
+      yield self if block_given?
+    end
+    def add_author(name, email = nil)
+      @authors << {:name => name, :email => email}
+    end
+    alias_method :author, :add_author
+    alias_method :add, :add_author
+    
+    def to_groff
+      GroffString.groffify do |out|
+        out.section "authors"
+        @authors.each do |author|
+          args = ["\"#{author[:name]}\""]
+          if author[:email] then args << "Aq" << author[:email] end
+          out.An *args
+        end
+      end
+    end
+  end
+end
+        

data/lib/rtfm/sections/description.rb

@@ -0,0 +1,32 @@
+module RTFM
+  class DescriptionSection < Struct.new(:body, :options)
+    def initialize(*args)
+      super
+      self.options ||= []
+      yield self if block_given?
+    end
+    
+    def add_option(*args)
+      if args.size == 1 && args.first.is_a?(Option)
+      then self.options << args.first
+      else self.options << Option.new(*args)
+      end
+    end
+    alias_method :option, :add_option
+    
+    def to_groff
+      GroffString.groffify do |out|
+        out.section "description"
+        out << self.body
+        if options.any?
+          out.Bl "-tag", "-width", "\"mmmmmmmmmm\"", "-compact"
+          options.each do |option|
+            out << option.to_groff(:item)
+          end
+          out.El
+          out.Pp
+        end
+      end
+    end
+  end
+end

data/lib/rtfm/sections/see_also.rb

@@ -0,0 +1,24 @@
+module RTFM
+  class SeeAlsoSection
+    def initialize
+      @references = {}
+      yield self if block_given?
+    end
+    def reference(title, section = 0)
+      (@references[section] ||= []) << title
+    end
+    def to_groff
+      GroffString.groffify do |out|
+        out.section "SEE ALSO"
+        @references.keys.sort.each do |section|
+          @references[section].sort.each do |title|
+            if section == 0
+            then out.reference title
+            else out.reference title, section
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rtfm/sections/synopsis.rb

@@ -0,0 +1,41 @@
+module RTFM
+  class SynopsisSection
+    def initialize
+      @options = []
+      yield self if block_given?
+    end
+    
+    def add_option(*args)
+      if args.size == 1 && args.first.is_a?(Option)
+      then @options << args.first
+      else @options << Option.new(*args)
+      end
+    end
+    alias_method :option, :add_option
+    
+    def compare_flags(a, b)
+      a_ord, b_ord = a.ord, b.ord
+      if ('0'.ord .. '9'.ord).include?(a_ord)
+        a_ord += 'z'.ord
+      end
+      if ('0'.ord .. '9'.ord).include?(b_ord)
+        b_ord += 'z'.ord
+      end
+      a_ord <=> b_ord
+    end
+    
+    def to_groff
+      flags = @options.select {|opt| opt.title.size == 1 && !opt.argument}
+      long_args = @options - flags
+      
+      GroffString.groffify do |out|
+        out.section "synopsis"
+        out.put_name
+        out.Op "Fl", flags.map {|flag| flag.title}.sort {|a, b| compare_flags(a,b)}.join
+        long_args.each do |opt|
+          out << opt.to_groff(:option)
+        end
+      end
+    end
+  end
+end

data/lib/rtfm/sections/text.rb

@@ -0,0 +1,10 @@
+module RTFM
+  class TextSection < Struct.new(:title, :body)
+    def to_groff
+      GroffString.groffify do |out|
+        out.section title.to_s.upcase
+        out << body.to_s
+      end
+    end
+  end
+end

data/lib/rtfm/tasks.rb

@@ -0,0 +1,44 @@
+require 'rake'
+require 'rtfm'
+
+namespace :man do
+  desc "Display your man files in man."
+  task :debug do
+    require 'tempfile'
+    require 'rtfm'
+    RTFM::ManPage.all_pages.each do |page|
+      Tempfile.open("#{page.name}.#{page.section}") do |f|
+        f << page.to_groff
+        f.flush
+        system("man #{f.path}")
+      end
+    end
+  end
+  
+  desc "Generate your manual files in the man/ directory"
+  task :gen do
+    FileUtils.makedirs "man/"
+    RTFM::ManPage.all_pages.each do |page|
+      File.open("man/#{page.name}.#{page.section}", "w") do |f|
+        f << page.to_groff
+      end
+    end
+  end
+  
+  desc "Install your manual files globally"
+  task :install => :gen do
+    if Rake.application.unix?
+      Dir["man/*"].each do |manfile|
+        section = manfile.split(".").last
+        begin
+          FileUtils.cp(manfile, "/usr/share/man/man#{section}/")
+        rescue Errno::EACCES
+          puts "I'm sorry, but you need root privileges to install man pages with this version"+
+               " of RTFM."
+        end
+      end
+    else
+      raise "Can't install man pages without a unix-based OS."
+    end
+  end
+end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,171 @@
+require 'rubygems/command_manager'
+
+require 'rubygems/command'
+require 'rubygems_analyzer'
+
+class Gem::Commands::ManCommand < Gem::Command
+
+  def initialize
+    super 'man', 'Manage man-files bundled with gems'
+    options[:action] = :install
+    
+    add_option('-v', '--view', "Views the manual files included in",
+                               "the gem.") do |value, options|
+      options[:action] = :view
+    end
+    
+    add_option('-i', '--install', "Installs all the gem's manual files globally") do |value, options|
+      options[:action] = :install
+    end
+    
+    add_option('-r', '--remove', "Removes the gem's manual files globally") do |value, options|
+      options[:action] = :remove
+    end
+  end
+
+  def execute
+    if Gem.win_platform? || !has_man?
+      alert_error "You must have the 'man' command to use this extension."
+      return
+    end
+    
+    get_all_gem_names.each do |name|
+      path = get_path name, options[:version]
+      if path then
+        man_path = File.join path, 'man'
+        if File.exist?(man_path) && File.directory?(man_path) then
+          Dir[File.join man_path, "**"].each do |man_file|
+            dispatch(man_file)
+          end
+        else
+          alert_error "Gem '#{name}' does not appear to have packaged man files."
+        end
+      else
+        alert_error "Gem '#{name}' not installed."
+      end
+    end
+  end
+
+  
+  def dispatch(file)
+    case options[:action]
+    when :install
+      install(file)
+    when :view
+      view(file)
+    when :remove
+      remove(file)
+    end
+  end
+  
+  
+  MAN_DIR = "/usr/share/man/"
+  
+  ##
+  # Views the man file in the man program
+  def view(source)
+    system("man #{source}")
+  end
+  
+  ##
+  # Installs the given file into the appropriate man directory.
+  def install(source)
+    full_name = File.split(source).last
+    section = full_name.split(".").last
+    destination = File.join MAN_DIR, "man#{section}", full_name
+    File.open(destination, "wb") do |out|
+      out << watermark_file(source)
+    end
+  end
+  
+  ##
+  # Installs the given file into the appropriate man directory.
+  def remove(source)
+    full_name = File.split(source).last
+    section = full_name.split(".").last
+    destination = File.join MAN_DIR, "man#{section}", full_name
+    if is_watermarked_file?(destination)
+      FileUtils.unlink(destination)
+    else
+      alert_error "The man file at #{destination} was not installed by Rubygems. It has "+
+                  "not been deleted."
+    end
+  end
+  
+  def watermark
+    %Q{.\\" Installed by Rubygems' Man Extension\n}
+  end
+  
+  ##
+  # Watermarks a man page. Assumes input file is not already compressed.
+  def watermark_file(file)
+    add_watermark(File.read(file))
+  end
+  
+  ##
+  # Watermarks some groff text, so you can tell it's been rubygem'd
+  def add_watermark(text)
+    "#{watermark}#{text}"
+  end
+  
+  ##
+  # Watermarks a man page. Assumes input file is not already compressed.
+  def is_watermarked_file?(file)
+    is_watermarked?(File.read(file))
+  end
+  
+  ##
+  # Is the given text watermarked?
+  def is_watermarked?(text)
+    text[0..(watermark.size-1)] == watermark
+  end
+  
+  # Return the full path to the cached gem file matching the given
+  # name and version requirement.  Returns 'nil' if no match.
+  #
+  # Example:
+  #
+  #   get_path('rake', '> 0.4')   # -> '/usr/lib/ruby/gems/1.8/cache/rake-0.4.2.gem'
+  #   get_path('rake', '< 0.1')   # -> nil
+  #   get_path('rak')             # -> nil (exact name required)
+  #--
+  # TODO: This should be refactored so that it's a general service. I don't
+  # think any of our existing classes are the right place though.  Just maybe
+  # 'Cache'?
+  #
+  # TODO: It just uses Gem.dir for now.  What's an easy way to get the list of
+  # source directories?
+  def get_path(gemname, version_req)
+    return gemname if gemname =~ /\.gem$/i
+
+    specs = Gem::source_index.find_name gemname, version_req
+
+    selected = specs.sort_by { |s| s.version }.last
+
+    return nil if selected.nil?
+
+    # We expect to find (basename).gem in the 'cache' directory.
+    # Furthermore, the name match must be exact (ignoring case).
+    if gemname =~ /^#{selected.name}$/i
+      filename = selected.full_name
+      path = nil
+
+      Gem.path.find do |gem_dir|
+        path = File.join gem_dir, 'gems', filename
+        File.exist? path
+      end
+
+      path
+    else
+      nil
+    end
+  end
+
+  def has_man?
+    system("man 1>/dev/null 2>&1")
+  end
+
+end
+
+Gem::CommandManager.instance.register_command :man
+

data/man/testing.2

@@ -0,0 +1,54 @@
+.\" Hello it's a comment
+.Dd January 09, 2010
+.Os
+.Dt testing 2
+.Sh NAME
+.Nm testing
+.Nd testing man page
+.Sh SYNOPSIS
+.Nm
+.Op Fl AZjkr0
+.Op Fl verbose
+.Op Fl silliness Ar n
+.Op Fl input Ao input Ac
+.Sh DESCRIPTION
+This is a small, temporary description of the testing man page.
+.Bl -tag -width "mmmmmmmmmm" -compact
+.Pp
+.It Fl r
+Some r flag
+.Pp
+.It Fl j
+Some j flag
+.Pp
+.It Fl k
+Some k flag
+.Pp
+.It Fl 0
+Some zero flag
+.Pp
+.It Fl A
+Some capitalized flag
+.Pp
+.It Fl Z
+some big-z flag
+.Pp
+.It Fl verbose
+The verbose flag does a lot of stuff.
+.Pp
+.It Fl silliness Ar n
+Set how silly the application should be.
+.Pp
+.It Fl input Ao input Ac
+The input flag takes a filename
+.El
+.Pp
+.Sh SEE ALSO
+.Xr ruby
+.Xr rails 1
+.Sh HISTORY
+This program has a storied history that I am too lazy to include here.
+.Sh AUTHORS
+.An "Michael Edgar" Aq adgar@carboni.ca
+.Sh BUGS
+There are a few bugs, but nothing too serious.

data/spec/authors_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe "authors section" do
+  before do
+    @authors = AuthorsSection.new do |sect|
+                 sect.author "Michael Edgar"
+                 sect.author "Ari Brown", "seydar@carboni.ca"
+               end
+    @groffed = @authors.to_groff
+  end
+  
+  it "makes an authors section" do
+    @groffed.should.match(/^\.Sh AUTHORS$/)
+  end
+  
+  it "adds an author without an email" do
+    @groffed.should.match(/^\.An "Michael Edgar"$/)
+  end
+  
+  it "adds an author with an email" do
+    @groffed.should.match(/^\.An "Ari Brown" Aq seydar@carboni.ca/)
+  end
+end

data/spec/description_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+describe "description section" do
+  
+  FULL_DESC = "This is the description for the description section. Typically, this would" +
+              " be much longer, but for now, it is short. Huzzah!"
+  
+  before do
+    @desc = DescriptionSection.new do |desc|
+              desc.body = FULL_DESC
+              desc.option :verbose, "Makes output wordy and unnecessarily long"
+              desc.option :input, "Specifies an input file", :arg => "<file>"
+              desc.option :output, "Specifies an output file", :argument => "[output]"
+              desc.option :silly, "Has a silly argument", :arg => "silliness"
+            end
+    @groffed = @desc.to_groff
+  end
+  
+  it "creates a description section" do
+    @groffed.should.match(/^\.Sh DESCRIPTION$/)
+  end
+  
+  it "displays its body below the section header" do
+    @groffed.should.match(/^\.Sh DESCRIPTION\nThis is the/)
+  end
+  
+  it "contains the full body text" do
+    @groffed.should.include(FULL_DESC)
+  end
+  
+  it "creates a list for options" do
+    @groffed.should.match(/^\.Bl -tag/)
+  end
+  
+  it "creates list items with option names" do
+    @groffed.should.match(/^\.It Fl verbose/)
+    @groffed.should.match(/^\.It Fl input/)
+  end
+  
+  it "displays arguments for options" do
+    @groffed.should.match(/^\.It Fl silly Ar silliness/)
+  end
+  
+  it "changes arguments with angle brackets to proper groff" do
+    @groffed.should.match(/Ao file Ac/)
+  end
+  
+  it "changes arguments with square brackets to proper groff" do
+    @groffed.should.match(/Oo output Oc/)
+  end
+  it "puts option descriptions next to option names" do
+    @groffed.should.match(/^\.It Fl verbose\nMakes output wordy/)
+  end
+  
+end

data/spec/groffstring_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe "groff_string" do
+  before do
+    @groff = GroffString.new
+    @groff_with_line = GroffString.new("Some text")
+  end
+  
+  it "uses its initial value" do
+    @groff.to_s.should.equal ""
+    @groff_with_line.to_s.should.equal("Some text")
+  end
+  
+  it "converts to a string" do
+    @groff.should.respond_to(:to_s)
+  end
+  
+  it "adds references using the .Xr macro" do
+    @groff.reference("rails", 1)
+    @groff.to_s.should.include(".Xr rails 1")
+  end
+  
+  it "generates sections" do
+    @groff.section("NAME")
+    @groff.to_s.should.include(".Sh NAME")
+  end
+  
+  it "generates arbitrary macros" do
+    @groff.Br("some", "arguments", :here)
+    @groff.to_s.should.include(".Br some arguments here")
+  end
+  
+  it "adds lines using add_line" do
+    @groff.add_line("some arbitrary line goes here")
+    @groff.to_s.should.include("some arbitrary line goes here\n")
+  end
+  
+  it "adds lines with <<" do
+    @groff << "werd some line"
+    @groff.to_s.should.include("werd some line\n")
+  end
+end

data/spec/rtfm_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe "rtfm" do
+  before do
+    @rtfm = ManPage.new("testing", 2) do |page|
+              page.date = Date.parse("1/2/2010")
+              page.summary = "testing man page"
+              page.see_also do |also|
+                also.reference "madeup", 4
+                also.reference "rails", 1
+                also.reference "ruby"
+                also.reference "perl", 1
+              end
+              page.bugs = "There are a few bugs, but nothing too serious."
+              page.history = "This program has a storied history that I am too lazy to include here."
+            end
+    @groff = @rtfm.to_groff
+  end
+  
+  it "displays the correct date" do
+    @groff.should.match(/^\.Dd January 02, 2010$/)
+  end
+  
+  it "has a NAME section" do
+    @groff.should.match(/^\.Sh NAME$/)
+  end
+  
+  it "generates a name line" do
+    @groff.should.match(/^\.Nm testing/)
+  end
+  
+  it "generates a summary line" do
+    @groff.should.match(/^\.Nd testing man page/)
+  end
+  
+  describe "rtfm-sections" do
+    it "has a bugs section" do
+      @groff.should.match(/^\.Sh BUGS$/)
+    end
+    
+    it "includes its bugs text" do
+      @groff.should.match(/^There are a few bugs/)
+    end
+    
+    it "has a history section" do
+      @groff.should.match(/^\.Sh HISTORY$/)
+    end
+    
+    it "includes its history text" do
+      @groff.should.match(/^This program has a storied history/)
+    end
+  end
+end

data/spec/see_also_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+describe "see also section" do
+  before do
+    @see_also = SeeAlsoSection.new do |also|
+                  also.reference "madeup", 4
+                  also.reference "rails", 1
+                  also.reference "ruby"
+                  also.reference "perl", 1
+                end
+  end
+  
+  it "has a see also section" do
+    @see_also.to_groff.should.match(/^\.Sh SEE ALSO/)
+  end
+  
+  it "includes references in its see also section" do
+    groffed = @see_also.to_groff
+    groffed.should.match(/^\.Xr rails 1$/)
+    groffed.should.match(/^\.Xr ruby$/)
+    groffed.should.match(/^\.Xr perl 1$/)
+    groffed.should.match(/^\.Xr madeup 4$/)
+  end
+  
+  it "sorts by section" do
+    groffed = @see_also.to_groff
+    groffed.index(/^\.Xr ruby$/).should.be < groffed.index(/^\.Xr rails 1$/)
+    groffed.index(/^\.Xr rails 1$/).should.be < groffed.index(/^\.Xr madeup 4$/)
+  end
+  
+  it "sorts within sections" do
+    groffed = @see_also.to_groff
+    groffed.index(/^\.Xr perl 1$/).should.be < groffed.index(/^\.Xr rails 1$/)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'bacon'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rtfm'
+
+include RTFM
+
+Bacon.summary_on_exit

data/spec/synopsis_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+describe "synopsis section" do
+  
+  before do
+    @synopsis = SynopsisSection.new do |syno|
+                  syno.option :r, "Some r flag"
+                  syno.option :j, "Some j flag"
+                  syno.option :k, "Some k flag"
+                  syno.option :"0", "Some zero flag"
+                  syno.option :A, "Some capitalized flag"
+                  syno.option :Z, "some big-z flag"
+                  syno.option :verbose, "The verbose flag does a lot of stuff."
+                  syno.option :silliness, "Set how silly the application should be.", :argument => "n"
+                  syno.option :input, "The input flag takes a filename", :argument => "<input>"
+                end
+    @groffed = @synopsis.to_groff
+  end
+  
+  it "contains the name of the man page" do
+    @groffed.should.match(/^\.Nm$/)
+  end
+  
+  it "displays long-form flags" do
+    @groffed.should.match(/^\.Op Fl verbose$/)
+  end
+  
+  it "combines short-form flags into one entry" do
+    @groffed.should.match(/^\.Op Fl ([rjk0AZ]{6})/)
+  end
+  
+  it "sorts short-form flags within their entry" do
+    @groffed.should.match(/AZjkr0/)
+  end
+  
+  it "encodes < and > in option arguments" do
+    @groffed.should.match(/Ao input Ac/)
+  end
+  
+  it "underlines arguments" do
+    @groffed.should.match(/\.Op Fl silliness Ar n/)
+  end
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: rtfm
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+platform: ruby
+authors: 
+- Michael Edgar
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-10 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bacon
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: |
+  Using RTFM, you can declaratively create nice, standard man pages for your 
+  Ruby projects using a slick, maintainable DSL. It also includes rake tasks 
+  to aid in debugging, generating, and installing your man files.
+
+email: michael.j.edgar@dartmouth.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/rtfm.rb
+- lib/rtfm/groffstring.rb
+- lib/rtfm/manpage.rb
+- lib/rtfm/option.rb
+- lib/rtfm/sections/authors.rb
+- lib/rtfm/sections/description.rb
+- lib/rtfm/sections/see_also.rb
+- lib/rtfm/sections/synopsis.rb
+- lib/rtfm/sections/text.rb
+- lib/rtfm/tasks.rb
+- lib/rubygems_plugin.rb
+- man/testing.2
+- spec/authors_spec.rb
+- spec/description_spec.rb
+- spec/groffstring_spec.rb
+- spec/rtfm_spec.rb
+- spec/see_also_spec.rb
+- spec/spec_helper.rb
+- spec/synopsis_spec.rb
+has_rdoc: true
+homepage: http://github.com/michaeledgar/rtfm
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Create makefiles declaratively. Comes with rake tasks.
+test_files: 
+- spec/authors_spec.rb
+- spec/description_spec.rb
+- spec/groffstring_spec.rb
+- spec/rtfm_spec.rb
+- spec/see_also_spec.rb
+- spec/spec_helper.rb
+- spec/synopsis_spec.rb