md2man 1.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 +36 -0
- data/LICENSE +15 -0
- data/README.markdown +106 -0
- data/Rakefile +1 -0
- data/bin/md2man +70 -0
- data/lib/md2man/engine.rb +18 -0
- data/lib/md2man/roff.rb +851 -0
- data/lib/md2man/version.rb +3 -0
- data/lib/md2man.rb +2 -0
- data/man/man1/md2man.1 +79 -0
- data/md2man.gemspec +25 -0
- data/test/md2man/roff_test.rb +584 -0
- data/test/test_helper.rb +2 -0
- metadata +125 -0
data/.gitignore
ADDED
data/Gemfile
ADDED
data/HISTORY.markdown
ADDED
@@ -0,0 +1,36 @@
|
|
1
|
+
------------------------------------------------------------------------------
|
2
|
+
Version 1.0.1 (2011-12-06)
|
3
|
+
------------------------------------------------------------------------------
|
4
|
+
|
5
|
+
Breaking changes:
|
6
|
+
|
7
|
+
* Renamed the project from "redcarpet-manpage" to "md2man".
|
8
|
+
|
9
|
+
* `RedcarpetManpage::Renderer` is now `Md2Man::Engine`.
|
10
|
+
|
11
|
+
* `RedcarpetManpage::RENDERER` is now `Md2Man::ENGINE`.
|
12
|
+
|
13
|
+
* Tagged paragraphs no longer require the first line to begin with italic or
|
14
|
+
bold styling. All that matters is that the subsequent lines are indented.
|
15
|
+
|
16
|
+
External changes:
|
17
|
+
|
18
|
+
* Added md2man(1) executable for command-line usage.
|
19
|
+
|
20
|
+
* Added support for all HTML 4.0 and XHTML 1.0 entities.
|
21
|
+
|
22
|
+
* Added support for tables, horizontal rules, and more.
|
23
|
+
|
24
|
+
* Added `Md2Man::Roff` mixin for advanced Redcarpet2 usage.
|
25
|
+
|
26
|
+
* Improved README with some new and revised documentation.
|
27
|
+
|
28
|
+
Internal changes:
|
29
|
+
|
30
|
+
* Rewrote entire Markdown to Roff conversion from scratch while doing TDD.
|
31
|
+
|
32
|
+
------------------------------------------------------------------------------
|
33
|
+
Version 0.0.1 (2011-10-13)
|
34
|
+
------------------------------------------------------------------------------
|
35
|
+
|
36
|
+
* 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.
|
data/README.markdown
ADDED
@@ -0,0 +1,106 @@
|
|
1
|
+
md2man - write UNIX man pages in Markdown
|
2
|
+
==============================================================================
|
3
|
+
|
4
|
+
md2man is a Ruby library and command-line program that converts [Markdown]
|
5
|
+
documents into UNIX man pages (really [Roff] documents) using [Redcarpet2].
|
6
|
+
|
7
|
+
[Roff]: http://troff.org
|
8
|
+
[Markdown]: http://daringfireball.net/projects/markdown/
|
9
|
+
[Redcarpet2]: https://github.com/tanoku/redcarpet
|
10
|
+
|
11
|
+
------------------------------------------------------------------------------
|
12
|
+
Installation
|
13
|
+
------------------------------------------------------------------------------
|
14
|
+
|
15
|
+
As a Ruby gem:
|
16
|
+
|
17
|
+
gem install md2man
|
18
|
+
|
19
|
+
As a Git clone:
|
20
|
+
|
21
|
+
git clone git://github.com/sunaku/md2man
|
22
|
+
cd md2man
|
23
|
+
bundle install
|
24
|
+
|
25
|
+
------------------------------------------------------------------------------
|
26
|
+
Command Usage
|
27
|
+
------------------------------------------------------------------------------
|
28
|
+
|
29
|
+
Read the manual page:
|
30
|
+
|
31
|
+
md2man --help
|
32
|
+
|
33
|
+
------------------------------------------------------------------------------
|
34
|
+
Library Usage
|
35
|
+
------------------------------------------------------------------------------
|
36
|
+
|
37
|
+
Use the default renderer:
|
38
|
+
|
39
|
+
require 'md2man'
|
40
|
+
your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
|
41
|
+
|
42
|
+
Build your own renderer:
|
43
|
+
|
44
|
+
require 'md2man'
|
45
|
+
engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash)
|
46
|
+
your_roff_output = engine.render(your_markdown_input)
|
47
|
+
|
48
|
+
Define your own renderer:
|
49
|
+
|
50
|
+
require 'md2man'
|
51
|
+
|
52
|
+
class YourManpageRenderer < Md2Man::Engine
|
53
|
+
# ... your stuff here ...
|
54
|
+
end
|
55
|
+
|
56
|
+
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
|
57
|
+
your_roff_output = engine.render(your_markdown_input)
|
58
|
+
|
59
|
+
Mix-in your own renderer:
|
60
|
+
|
61
|
+
require 'md2man'
|
62
|
+
|
63
|
+
class YourManpageRenderer < Redcarpet::Render::Base
|
64
|
+
include Md2Man::Roff
|
65
|
+
# ... your stuff here ...
|
66
|
+
end
|
67
|
+
|
68
|
+
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
|
69
|
+
your_roff_output = engine.render(your_markdown_input)
|
70
|
+
|
71
|
+
------------------------------------------------------------------------------
|
72
|
+
Document Format
|
73
|
+
------------------------------------------------------------------------------
|
74
|
+
|
75
|
+
md2man attaches the following additional semantics to its [Markdown] input:
|
76
|
+
|
77
|
+
* There can be at most one top-level heading (H1). It is emitted as `.TH`
|
78
|
+
in the [Roff] output, specifying the UNIX man page's header and footer.
|
79
|
+
|
80
|
+
* Paragraphs whose lines are all uniformly indented by two spaces are
|
81
|
+
considered to be "indented paragraphs". They are unindented accordingly
|
82
|
+
before emission as `.IP` in the [Roff] output.
|
83
|
+
|
84
|
+
* Paragraphs whose subsequent lines (all except the first) are uniformly
|
85
|
+
indented by two spaces are considered to be a "tagged paragraphs". They
|
86
|
+
are unindented accordingly before emission as `.TP` in the [Roff] output.
|
87
|
+
|
88
|
+
------------------------------------------------------------------------------
|
89
|
+
Limitations
|
90
|
+
------------------------------------------------------------------------------
|
91
|
+
|
92
|
+
At present, md2man does not translate the following [Redcarpet2] node types:
|
93
|
+
|
94
|
+
* `block_html`
|
95
|
+
* `strikethrough`
|
96
|
+
* `superscript`
|
97
|
+
* `image`
|
98
|
+
* `raw_html`
|
99
|
+
|
100
|
+
It issues a warning when it encounters these instead. Patches are welcome!
|
101
|
+
|
102
|
+
------------------------------------------------------------------------------
|
103
|
+
License
|
104
|
+
------------------------------------------------------------------------------
|
105
|
+
|
106
|
+
Released under the ISC license. See the LICENSE file for details.
|
data/Rakefile
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
require "bundler/gem_tasks"
|
data/bin/md2man
ADDED
@@ -0,0 +1,70 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
=begin
|
3
|
+
|
4
|
+
MD2MAN 1 "2011-12-06" "1.0.1"
|
5
|
+
=============================
|
6
|
+
|
7
|
+
NAME
|
8
|
+
----
|
9
|
+
|
10
|
+
md2man - convert markdown(7) into roff(7)
|
11
|
+
|
12
|
+
SYNOPSIS
|
13
|
+
--------
|
14
|
+
|
15
|
+
`md2man` [*OPTION*]... [*FILE*]
|
16
|
+
|
17
|
+
DESCRIPTION
|
18
|
+
-----------
|
19
|
+
|
20
|
+
[md2man] converts markdown(7) input from the given *FILE* into roff(7) using
|
21
|
+
[Redcarpet2] and then prints the result to the standard output stream. If
|
22
|
+
*FILE* is not given, then the standard input stream is read in its place.
|
23
|
+
|
24
|
+
### Document Format
|
25
|
+
|
26
|
+
The following additional semantics are attached to markdown(7):
|
27
|
+
|
28
|
+
* There can be at most one top-level heading (H1). It is emitted as `.TH`
|
29
|
+
in the roff(7) output, specifying the UNIX man page's header and footer.
|
30
|
+
|
31
|
+
* Paragraphs whose lines are all uniformly indented by two spaces are
|
32
|
+
considered to be "indented paragraphs". They are unindented accordingly
|
33
|
+
before emission as `.IP` in the roff(7) output.
|
34
|
+
|
35
|
+
* Paragraphs whose subsequent lines (all except the first) are uniformly
|
36
|
+
indented by two spaces are considered to be a "tagged paragraphs". They
|
37
|
+
are unindented accordingly before emission as `.TP` in the roff(7) output.
|
38
|
+
|
39
|
+
### Markdown Extensions
|
40
|
+
|
41
|
+
The following [Redcarpet2] extensions for markdown(7) are enabled:
|
42
|
+
|
43
|
+
* tables
|
44
|
+
* autolink
|
45
|
+
* superscript
|
46
|
+
* strikethrough
|
47
|
+
* no_intra_emphasis
|
48
|
+
* fenced_code_blocks
|
49
|
+
|
50
|
+
OPTIONS
|
51
|
+
-------
|
52
|
+
|
53
|
+
`-h`, `--help`
|
54
|
+
Display this help manual using man(1).
|
55
|
+
|
56
|
+
SEE ALSO
|
57
|
+
--------
|
58
|
+
|
59
|
+
markdown(7), roff(7)
|
60
|
+
|
61
|
+
[md2man]: https://github.com/sunaku/md2man
|
62
|
+
[Redcarpet2]: https://github.com/tanoku/redcarpet
|
63
|
+
|
64
|
+
=end =========================================================================
|
65
|
+
|
66
|
+
require 'binman'
|
67
|
+
BinMan.help
|
68
|
+
|
69
|
+
require 'md2man'
|
70
|
+
puts Md2Man::ENGINE.render(ARGF.read)
|
@@ -0,0 +1,18 @@
|
|
1
|
+
require 'redcarpet'
|
2
|
+
require 'md2man/roff'
|
3
|
+
|
4
|
+
module Md2Man
|
5
|
+
class Engine < Redcarpet::Render::Base
|
6
|
+
include Roff
|
7
|
+
end
|
8
|
+
|
9
|
+
ENGINE = Redcarpet::Markdown.new(
|
10
|
+
Md2Man::Engine,
|
11
|
+
:tables => true,
|
12
|
+
:autolink => true,
|
13
|
+
:superscript => true,
|
14
|
+
:strikethrough => true,
|
15
|
+
:no_intra_emphasis => true,
|
16
|
+
:fenced_code_blocks => true
|
17
|
+
)
|
18
|
+
end
|