binman 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ *.gem
2
+ .bundle
3
+ Gemfile.lock
4
+ pkg/*
data/Gemfile ADDED
@@ -0,0 +1,4 @@
1
+ source "http://rubygems.org"
2
+
3
+ # Specify your gem's dependencies in binman.gemspec
4
+ gemspec
@@ -0,0 +1,5 @@
1
+ ------------------------------------------------------------------------------
2
+ Version 0.0.1 (2011-10-12)
3
+ ------------------------------------------------------------------------------
4
+
5
+ * First release! Happy birthday! Woohoo! :-)
data/LICENSE ADDED
@@ -0,0 +1,15 @@
1
+ (the ISC license)
2
+
3
+ Copyright 2011 Suraj N. Kurapati <sunaku@gmail.com>
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
@@ -0,0 +1,83 @@
1
+ binman - UNIX man pages for Ruby bin/ scripts
2
+ ==============================================================================
3
+
4
+ [binman] produces UNIX man pages for your Ruby `bin/` scripts using
5
+ markdown(7), roff(7), [Redcarpet2] for conversion thereof, and man(1).
6
+
7
+ [binman]: https://github.com/sunaku/binman
8
+ [binman-api]: http://rdoc.info/github/sunaku/binman
9
+ [Redcarpet2]: https://github.com/tanoku/redcarpet
10
+
11
+ ------------------------------------------------------------------------------
12
+ Features
13
+ ------------------------------------------------------------------------------
14
+
15
+ * Includes both a Ruby library and a command-line client.
16
+
17
+ * Individual extraction, conversion, and display commands.
18
+
19
+ * Implemented in less than 100 lines of pure Ruby code! :-)
20
+
21
+ ------------------------------------------------------------------------------
22
+ Prerequisites
23
+ ------------------------------------------------------------------------------
24
+
25
+ * Ruby 1.9.2 or newer. It might work with 1.8.7 but I haven't tried. :-P
26
+
27
+ ------------------------------------------------------------------------------
28
+ Installation
29
+ ------------------------------------------------------------------------------
30
+
31
+ As a Ruby gem:
32
+
33
+ gem install binman
34
+
35
+ As a Git clone:
36
+
37
+ git clone git://github.com/sunaku/binman
38
+ cd binman
39
+ bundle install
40
+
41
+ ------------------------------------------------------------------------------
42
+ Invocation
43
+ ------------------------------------------------------------------------------
44
+
45
+ If installed as a Ruby gem:
46
+
47
+ binman
48
+
49
+ If installed as a Git clone:
50
+
51
+ bundle exec ruby -Ilib bin/binman
52
+
53
+ Just pass `--help` to see its man page.
54
+
55
+ ------------------------------------------------------------------------------
56
+ Usage
57
+ ------------------------------------------------------------------------------
58
+
59
+ ### In your bin/ scripts
60
+
61
+ Add the following lines to your bin/ script and you've got `--help` options!
62
+
63
+ require 'binman'
64
+ BinMan.help # show man page and exit if ARGV has -h or --help
65
+
66
+ Or, if you're on a diet:
67
+
68
+ require 'binman'
69
+ BinMan.show # just show the man page; no fancy extras, please!
70
+
71
+ See the [API documentation][binman-api] for more delicious recipes.
72
+
73
+ ### In your Rakefile
74
+
75
+ Add the following line to your `Rakefile` and you've got a `binman` task!
76
+
77
+ require 'binman/rake_tasks'
78
+
79
+ ------------------------------------------------------------------------------
80
+ License
81
+ ------------------------------------------------------------------------------
82
+
83
+ Released under the ISC license. See the LICENSE file for details.
@@ -0,0 +1,2 @@
1
+ require "bundler/gem_tasks"
2
+ require "binman/rake_tasks"
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ # BINMAN 1 "2011-10-12" "0.0.1" "Ruby User Manuals"
4
+ # =================================================
5
+ #
6
+ # NAME
7
+ # ----
8
+ #
9
+ # binman - UNIX man pages for Ruby `bin/` scripts
10
+ #
11
+ # SYNOPSIS
12
+ # --------
13
+ #
14
+ # `binman` [*OPTION*]... *COMMAND*
15
+ #
16
+ # DESCRIPTION
17
+ # -----------
18
+ #
19
+ # [binman] produces UNIX man pages for your Ruby `bin/` scripts by extracting
20
+ # their leading comment header (a contiguous sequence of single-line comments
21
+ # starting at beginning of file and ending at first single blank line) and
22
+ # then converting them from markdown(7) to roff(7) using [Redcarpet2] for
23
+ # display using man(1).
24
+ #
25
+ # See for more information and resources.
26
+ #
27
+ # ### Markdown Processing Extensions
28
+ #
29
+ # Although your leading comment headers are written in markdown(7), `binman`
30
+ # introduces the following additional conventions to simplify common tasks:
31
+ #
32
+ # 1. Paragraphs beginning with bold/italic and followed by at least
33
+ # one two-space indented line are considered to be definitions.
34
+ # The first line of such a paragraph is the term being defined and
35
+ # the subsequent two-space indented lines are the definition body.
36
+ #
37
+ # OPTIONS
38
+ # -------
39
+ #
40
+ # `-h`, `--help`
41
+ # Display this manual page using man(1).
42
+ #
43
+ # COMMANDS
44
+ # --------
45
+ #
46
+ # `read` [*FILE*]
47
+ # Print the leading comment header extracted from the given *FILE* or stdin.
48
+ #
49
+ # `dump` [*FILE*]
50
+ # Print the roff(7) conversion of the leading comment header extracted from
51
+ # the given *FILE* or stdin.
52
+ #
53
+ # `show` [*FILE*]
54
+ # Use man(1) to display the roff(7) conversion of the leading comment header
55
+ # extracted from the given *FILE* or stdin.
56
+ #
57
+ # SEE ALSO
58
+ # --------
59
+ #
60
+ # man(1), roff(7), markdown(7)
61
+ #
62
+ # [binman]: https://github.com/sunaku/binman
63
+ # [Redcarpet2]: https://github.com/tanoku/redcarpet
64
+ #
65
+
66
+ require 'binman'
67
+ BinMan.help
68
+
69
+ command, file = ARGV
70
+ file ||= STDIN
71
+
72
+ case command
73
+ when 'read' then puts BinMan.read(file)
74
+ when 'dump' then puts BinMan.dump(BinMan.read(file))
75
+ when 'show' then BinMan.show(file)
76
+ else warn "binman: unknown command: #{command}"; exit!
77
+ end
@@ -0,0 +1,23 @@
1
+ # -*- encoding: utf-8 -*-
2
+ $:.push File.expand_path("../lib", __FILE__)
3
+ require "binman/version"
4
+
5
+ Gem::Specification.new do |s|
6
+ s.name = "binman"
7
+ s.version = BinMan::VERSION
8
+ s.authors,
9
+ s.email = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
10
+ s.homepage = "http://github.com/sunaku/binman"
11
+ s.summary = "UNIX man pages for Ruby bin/ scripts"
12
+ s.description = nil
13
+
14
+ s.files = `git ls-files`.split("\n").concat(Dir['man/**/*'])
15
+ s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
16
+ s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
17
+ s.require_paths = ["lib"]
18
+
19
+ # specify any dependencies here; for example:
20
+ # s.add_development_dependency "rspec"
21
+ # s.add_runtime_dependency "rest-client"
22
+ s.add_runtime_dependency "redcarpet", ">= 2.0.0b5"
23
+ end
@@ -0,0 +1,61 @@
1
+ require "binman/version"
2
+
3
+ module BinMan
4
+ extend self
5
+
6
+ ##
7
+ # Returns content of leading comment header (a contiguous sequence of
8
+ # single-line comments starting at beginning of file and ending at first
9
+ # single blank line) from given source (IO, file name, or string).
10
+ #
11
+ # Comment markers and shebang line (if any) are removed from result.
12
+ #
13
+ def read source=nil
14
+ source = source.read if source.respond_to? :read
15
+ source ||=
16
+ if first_caller = caller.find {|f| not f.start_with? __FILE__ }
17
+ first_caller.sub(/:\d+.*$/, '')
18
+ end
19
+ source = File.read(source) if File.exist? source
20
+
21
+ string = source.to_s
22
+ string.split(/^\s*$/, 2).first.sub(/\A#!.+$/, '').gsub(/^# ?/, '').strip
23
+ end
24
+
25
+ ##
26
+ # Converts given leading comment header (produced by #read) into roff(7).
27
+ #
28
+ def dump header
29
+ require 'binman/renderer'
30
+ RENDERER.render(header)
31
+ end
32
+
33
+ ##
34
+ # Shows leading comment header from given source as UNIX man page.
35
+ #
36
+ def show source=nil
37
+ # try showing existing man page files for given source
38
+ return if source and File.exist? source and
39
+ File.exist? man_path = File.expand_path('../../man', source) and
40
+ system 'man', '-M', man_path, '-a', File.basename(source)
41
+
42
+ header = read(source)
43
+
44
+ begin
45
+ roff = dump(header)
46
+ IO.popen('man -l -', 'w') {|man| man.puts roff }
47
+ rescue
48
+ puts header
49
+ end
50
+ end
51
+
52
+ ##
53
+ # Shows leading comment header from given source as UNIX man page and exits.
54
+ #
55
+ def help source=nil, argv=ARGV
56
+ unless argv.grep(/^(-h|--help)$/).empty?
57
+ show source
58
+ exit
59
+ end
60
+ end
61
+ end
@@ -0,0 +1,18 @@
1
+ require 'rake'
2
+
3
+ path = 'man/man1'
4
+ bins = FileList['bin/*']
5
+ mans = bins.pathmap("#{path}/%n.1")
6
+
7
+ bins.zip(mans).each do |bin, man|
8
+ file man => [bin, path] do
9
+ require 'binman'
10
+ roff = BinMan.dump(BinMan.read(bin))
11
+ File.open(man, 'w') {|f| f << roff }
12
+ end
13
+ end
14
+
15
+
16
+ desc 'Build UNIX man pages for bin/ scripts.'
17
+ task :binman => mans
18
+ directory path
@@ -0,0 +1,55 @@
1
+ require 'redcarpet'
2
+ require 'redcarpet/render_man'
3
+
4
+ module BinMan
5
+ class Renderer < Redcarpet::Render::ManPage
6
+ def normal_text text
7
+ text.gsub(/(?<=\W)-(?=\W)/, '\\-') if text
8
+ end
9
+
10
+ def paragraph(text)
11
+ "\n.PP\n#{text}\n"
12
+ end
13
+
14
+ alias codespan double_emphasis
15
+ alias triple_emphasis double_emphasis
16
+
17
+ def autolink link, link_type
18
+ emphasis link
19
+ end
20
+
21
+ def link link, title, content
22
+ "#{triple_emphasis content} #{emphasis link}"
23
+ end
24
+
25
+ DEFINITION_INDENT = ' ' # two spaces
26
+
27
+ def postprocess document
28
+ document.
29
+ # squeeze blank lines to prevent double-spaced output
30
+ gsub(/^\n/, '').
31
+
32
+ # paragraphs beginning with bold/italic and followed by
33
+ # at least one definition-indented line are definitions
34
+ gsub(/^\.PP(?=\n\\f.+\n#{DEFINITION_INDENT}\S)/, '.TP').
35
+
36
+ # make indented paragraphs occupy less space on screen:
37
+ # roff will fit the second line of the paragraph along
38
+ # side the first line if it has enough room to do so!
39
+ gsub(/^#{DEFINITION_INDENT}(?=\S)/, '').
40
+
41
+ # encode references to other man pages as "hyperlinks"
42
+ gsub(/(\w+)(\([1-9nol]\)[[:punct:]]?\s*)/, "\n.BR \\1 \\2\n").
43
+ # keep the SEE ALSO sequence of references in-line
44
+ gsub(/(?:^\.BR.+\n)+/m){ |sequence| sequence.squeeze("\n") }
45
+ end
46
+ end
47
+
48
+ RENDERER = Redcarpet::Markdown.new(Renderer,
49
+ #:tables => true,
50
+ :autolink => true,
51
+ #:superscript => true,
52
+ :no_intra_emphasis => true,
53
+ :fenced_code_blocks => true,
54
+ :space_after_headers => true)
55
+ end
@@ -0,0 +1,3 @@
1
+ module BinMan
2
+ VERSION = "0.0.1"
3
+ end
@@ -0,0 +1,61 @@
1
+ .TH BINMAN 1 "2011-01-12" "0.0.1" "Ruby User Manuals"
2
+ .SH NAME
3
+ .PP
4
+ binman \- UNIX man pages for Ruby \fBbin/\fP scripts
5
+ .SH SYNOPSIS
6
+ .PP
7
+ \fBbinman\fP [\fIOPTION\fP]... \fICOMMAND\fP
8
+ .SH DESCRIPTION
9
+ .PP
10
+ \fBbinman\fP \fIhttps://github.com/sunaku/binman\fP produces UNIX man pages for your Ruby \fBbin/\fP scripts by extracting
11
+ their leading comment header (a contiguous sequence of single-line comments
12
+ starting at beginning of file and ending at first single blank line) and
13
+ then converting them from
14
+ .BR markdown (7)
15
+ to
16
+ .BR roff (7)
17
+ using \fBRedcarpet2\fP \fIhttps://github.com/tanoku/redcarpet\fP for
18
+ display using
19
+ .BR man (1).
20
+ .PP
21
+ See for more information and resources.
22
+ .SS Markdown Processing Extensions
23
+ .PP
24
+ Although your leading comment headers are written in
25
+ .BR markdown (7),
26
+ \fBbinman\fP
27
+ introduces the following additional conventions to simplify common tasks:
28
+ .nr step 0 1
29
+ .IP \n+[step]
30
+ Paragraphs beginning with bold/italic and followed by at least
31
+ one two-space indented line are considered to be definitions.
32
+ The first line of such a paragraph is the term being defined and
33
+ the subsequent two-space indented lines are the definition body.
34
+ .SH OPTIONS
35
+ .TP
36
+ \fB-h\fP, \fB--help\fP
37
+ Display this manual page using
38
+ .BR man (1).
39
+ .SH COMMANDS
40
+ .TP
41
+ \fBread\fP [\fIFILE\fP]
42
+ Print the leading comment header extracted from the given \fIFILE\fP or stdin.
43
+ .TP
44
+ \fBdump\fP [\fIFILE\fP]
45
+ Print the
46
+ .BR roff (7)
47
+ conversion of the leading comment header extracted from
48
+ the given \fIFILE\fP or stdin.
49
+ .TP
50
+ \fBshow\fP [\fIFILE\fP]
51
+ Use
52
+ .BR man (1)
53
+ to display the
54
+ .BR roff (7)
55
+ conversion of the leading comment header
56
+ extracted from the given \fIFILE\fP or stdin.
57
+ .SH SEE ALSO
58
+ .PP
59
+ .BR man (1),
60
+ .BR roff (7),
61
+ .BR markdown (7)
metadata ADDED
@@ -0,0 +1,70 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: binman
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.0.1
5
+ prerelease:
6
+ platform: ruby
7
+ authors:
8
+ - Suraj N. Kurapati
9
+ autorequire:
10
+ bindir: bin
11
+ cert_chain: []
12
+ date: 2011-10-13 00:00:00.000000000 Z
13
+ dependencies:
14
+ - !ruby/object:Gem::Dependency
15
+ name: redcarpet
16
+ requirement: &14739920 !ruby/object:Gem::Requirement
17
+ none: false
18
+ requirements:
19
+ - - ! '>='
20
+ - !ruby/object:Gem::Version
21
+ version: 2.0.0b5
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: *14739920
25
+ description: ''
26
+ email:
27
+ - sunaku@gmail.com
28
+ executables:
29
+ - binman
30
+ extensions: []
31
+ extra_rdoc_files: []
32
+ files:
33
+ - .gitignore
34
+ - Gemfile
35
+ - HISTORY.markdown
36
+ - LICENSE
37
+ - README.markdown
38
+ - Rakefile
39
+ - bin/binman
40
+ - binman.gemspec
41
+ - lib/binman.rb
42
+ - lib/binman/rake_tasks.rb
43
+ - lib/binman/renderer.rb
44
+ - lib/binman/version.rb
45
+ - man/man1/binman.1
46
+ homepage: http://github.com/sunaku/binman
47
+ licenses: []
48
+ post_install_message:
49
+ rdoc_options: []
50
+ require_paths:
51
+ - lib
52
+ required_ruby_version: !ruby/object:Gem::Requirement
53
+ none: false
54
+ requirements:
55
+ - - ! '>='
56
+ - !ruby/object:Gem::Version
57
+ version: '0'
58
+ required_rubygems_version: !ruby/object:Gem::Requirement
59
+ none: false
60
+ requirements:
61
+ - - ! '>='
62
+ - !ruby/object:Gem::Version
63
+ version: '0'
64
+ requirements: []
65
+ rubyforge_project:
66
+ rubygems_version: 1.8.11
67
+ signing_key:
68
+ specification_version: 3
69
+ summary: UNIX man pages for Ruby bin/ scripts
70
+ test_files: []