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.
- data/.gitignore +4 -0
- data/Gemfile +4 -0
- data/HISTORY.markdown +5 -0
- data/LICENSE +15 -0
- data/README.markdown +83 -0
- data/Rakefile +2 -0
- data/bin/binman +77 -0
- data/binman.gemspec +23 -0
- data/lib/binman.rb +61 -0
- data/lib/binman/rake_tasks.rb +18 -0
- data/lib/binman/renderer.rb +55 -0
- data/lib/binman/version.rb +3 -0
- data/man/man1/binman.1 +61 -0
- metadata +70 -0
data/.gitignore
ADDED
data/Gemfile
ADDED
data/HISTORY.markdown
ADDED
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.
|
data/README.markdown
ADDED
@@ -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.
|
data/Rakefile
ADDED
data/bin/binman
ADDED
@@ -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
|
data/binman.gemspec
ADDED
@@ -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
|
data/lib/binman.rb
ADDED
@@ -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
|
data/man/man1/binman.1
ADDED
@@ -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: []
|