Merge pull request #158 from avdv/man-page

Man page

README.md

@@ -42,6 +42,8 @@ A Ruby script that colorizes the `ls` output with color and icons. Here are the
 
 [(Back to top)](#table-of-contents)
 
+Man pages have been added. Checkout `man colorls`.
+
 ### Flags
 
 - With `-1` : Lists one entry per line

Rakefile

@@ -10,4 +10,31 @@ RuboCop::RakeTask.new do |task|
   task.requires << 'rubocop-rspec'
 end
 
+desc 'Build the manual'
+file 'man/colorls.1' => ['man/colorls.1.ronn', 'lib/colorls/flags.rb'] do
+  require 'colorls'
+  require 'ronn'
+
+  flags = ColorLS::Flags.new
+  attributes = {
+    date: Time.now,
+    manual: 'colorls Manual',
+    organization: "colorls #{ColorLS::VERSION}"
+  }
+  doc = Ronn::Document.new(nil, attributes) do
+    template = IO.read('man/colorls.1.ronn')
+
+    section = ''
+    flags.options.each do |o|
+      section += <<OPTION
+  * `#{o.flags.join('`, `')}`:
+     #{o.desc.join("<br>\n")}
+
+OPTION
+    end
+    template.sub('{{ OPTIONS }}', section)
+  end
+  IO.write('man/colorls.1', doc.convert('roff'))
+end
+
 task default: %w[spec rubocop]

colorls.gemspec

@@ -18,9 +18,12 @@ ColorLS::POST_INSTALL_MESSAGE = %(
     -t flag : Previously short for --tree, has been re-allocated to sort results by time
     -r flag : Previously short for --report, has been re-allocated to reverse sort results
 
+    Man pages have been added. Checkout `man colorls`.
+
   *******************************************************************
 ).freeze
 
+# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |spec|
   spec.name          = 'colorls'
   spec.version       = ColorLS::VERSION
@@ -31,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
+    f.match(%r{^(test|spec|features|man)/})
   end
   spec.bindir        = 'exe'
   spec.executables   = 'colorls'
@@ -40,11 +43,13 @@ Gem::Specification.new do |spec|
   spec.post_install_message = ColorLS::POST_INSTALL_MESSAGE
 
   spec.add_runtime_dependency 'filesize'
+  spec.add_runtime_dependency 'manpages'
   spec.add_runtime_dependency 'rainbow'
-  spec.add_runtime_dependency 'rake'
 
   spec.add_development_dependency 'bundler', '~> 1.15'
   spec.add_development_dependency 'diffy'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'ronn'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rspec-its'
   spec.add_development_dependency 'rubocop'

lib/colorls/flags.rb

@@ -1,5 +1,6 @@
 require 'optparse'
 require 'colorls/version'
+require 'ostruct'
 
 module ColorLS
   class Flags
@@ -42,6 +43,21 @@ module ColorLS
       end
     end
 
+    def options
+      list = @parser.top.list + @parser.base.list
+
+      result = list.collect do |o|
+        next unless o.respond_to? 'desc'
+
+        flags = o.short + o.long
+        next if flags.empty?
+
+        OpenStruct.new(flags: flags, desc: o.desc)
+      end
+
+      result.compact
+    end
+
     private
 
     def add_sort_options(options)
@@ -115,7 +131,7 @@ EXAMPLES
     end
 
     def parse_options
-      parser = OptionParser.new do |opts|
+      @parser = OptionParser.new do |opts|
         opts.banner = 'Usage:  colorls [OPTION]... [FILE]...'
         opts.separator ''
 
@@ -125,7 +141,7 @@ EXAMPLES
 
         opts.separator ''
         opts.on_tail('-h', '--help', 'prints this help') do
-          puts parser
+          puts @parser
           show_examples
           exit
         end
@@ -135,7 +151,7 @@ EXAMPLES
         end
       end
 
-      parser.parse!(@args)
+      @parser.parse!(@args)
 
       set_color_opts
     end

man/colorls.1

@@ -0,0 +1,135 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "COLORLS" "1" "November 2017" "colorls 1.0.9" "colorls Manual"
+.
+.SH "NAME"
+\fBcolorls\fR \- list directory contents with colors and icons
+.
+.SH "SYNOPSIS"
+\fBcolorls\fR [OPTION]\.\.\. [FILE]\.\.\.
+.
+.br
+.
+.SH "DESCRIPTION"
+List information about the given FILEs\. Uses different colors and icons for known file types\.
+.
+.P
+By default, the output is sorted alphabetically\.
+.
+.P
+Mandatory arguments to long options are mandatory for short options too\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+do not ignore entries starting with \.
+.
+.TP
+\fB\-A\fR, \fB\-\-almost\-all\fR
+do not list \. and \.\.
+.
+.TP
+\fB\-l\fR, \fB\-\-long\fR
+use a long listing format
+.
+.TP
+\fB\-\-tree\fR
+shows tree view of the directory
+.
+.TP
+\fB\-\-report\fR
+show brief report
+.
+.TP
+\fB\-1\fR
+list one file per line
+.
+.TP
+\fB\-d\fR, \fB\-\-dirs\fR
+show only directories
+.
+.TP
+\fB\-f\fR, \fB\-\-files\fR
+show only files
+.
+.TP
+\fB\-\-gs\fR, \fB\-\-git\-status\fR
+show git status for each file
+.
+.TP
+\fB\-\-sd\fR, \fB\-\-sort\-dirs\fR, \fB\-\-group\-directories\-first\fR
+sort directories first
+.
+.TP
+\fB\-\-sf\fR, \fB\-\-sort\-files\fR
+sort files first
+.
+.TP
+\fB\-t\fR
+sort by modification time, newest first
+.
+.TP
+\fB\-U\fR
+do not sort; list entries in directory order
+.
+.TP
+\fB\-S\fR
+sort by file size, largest first
+.
+.TP
+\fB\-\-sort\fR
+sort by WORD instead of name: none, size (\-S), time (\-t)
+.
+.TP
+\fB\-r\fR, \fB\-\-reverse\fR
+reverse order while sorting
+.
+.TP
+\fB\-\-light\fR
+use light color scheme
+.
+.TP
+\fB\-\-dark\fR
+use dark color scheme
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+prints this help
+.
+.TP
+\fB\-\-version\fR
+show version
+.
+.SH "EXAMPLES"
+.
+.TP
+show the given file:
+.
+.IP
+\fBcolorls README\.md\fR
+.
+.TP
+show matching files and list matching directories:
+.
+.IP
+\fBcolorls *\fR
+.
+.TP
+filter output by a regular expression:
+.
+.IP
+\fBcolorls | grep PATTERN\fR
+.
+.TP
+several short options can be combined:
+.
+.IP
+\fBcolorls \-d \-l \-a\fR
+.
+.br
+\fBcolorls \-dla\fR
+.
+.SH "AUTHOR"
+Written by Athitya Kumar\.

man/colorls.1.ronn

@@ -0,0 +1,41 @@
+colorls(1) -- list directory contents with colors and icons 
+===========================================================
+
+## SYNOPSIS
+
+`colorls` [OPTION]... [FILE]...<br>
+
+## DESCRIPTION
+
+List information about the given FILEs. Uses different colors and icons for known file types.
+
+By default, the output is sorted alphabetically.
+
+Mandatory arguments to long options are mandatory for short options too.
+
+## OPTIONS
+
+{{ OPTIONS }}
+
+## EXAMPLES
+
+  * show the given file:
+
+    `colorls README.md`
+
+  * show matching files and list matching directories:
+
+    `colorls *`
+
+  * filter output by a regular expression:
+
+    `colorls | grep PATTERN`
+
+  * several short options can be combined:
+
+    `colorls -d -l -a`<br>
+    `colorls -dla`
+
+## AUTHOR
+
+Written by Athitya Kumar.