Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 158 lines (115 sloc) 4.128 kB
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
1 md2man - write UNIX man pages in Markdown
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
2 ==============================================================================
22daadf @vmg Add sample Manpage renderer
vmg authored
3
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
4 md2man is a Ruby library and command-line program that converts [Markdown]
5 documents into UNIX man pages (really [Roff] documents) using [Redcarpet2].
22daadf @vmg Add sample Manpage renderer
vmg authored
6
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
7 [Roff]: http://troff.org
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
8 [Markdown]: http://daringfireball.net/projects/markdown/
9 [Redcarpet2]: https://github.com/tanoku/redcarpet
22daadf @vmg Add sample Manpage renderer
vmg authored
10
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
11 ------------------------------------------------------------------------------
12 Installation
13 ------------------------------------------------------------------------------
22daadf @vmg Add sample Manpage renderer
vmg authored
14
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
15 As a Ruby gem:
22daadf @vmg Add sample Manpage renderer
vmg authored
16
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
17 gem install md2man
22daadf @vmg Add sample Manpage renderer
vmg authored
18
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
19 As a Git clone:
22daadf @vmg Add sample Manpage renderer
vmg authored
20
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
21 git clone git://github.com/sunaku/md2man
22 cd md2man
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
23 bundle install
22daadf @vmg Add sample Manpage renderer
vmg authored
24
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
25 ------------------------------------------------------------------------------
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
26 Command Usage
27 ------------------------------------------------------------------------------
28
29 Read the manual page:
30
31 md2man --help
32
33 ------------------------------------------------------------------------------
34 Library Usage
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
35 ------------------------------------------------------------------------------
22daadf @vmg Add sample Manpage renderer
vmg authored
36
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
37 Use the default renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored
38
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
39 require 'md2man'
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
40 your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
41
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
42 Build your own renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored
43
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
44 require 'md2man'
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
45 engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash)
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
46 your_roff_output = engine.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
47
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
48 Define your own renderer:
49
50 require 'md2man'
51
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
52 class YourManpageRenderer < Md2Man::Engine
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
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
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
64 include Md2Man::Roff
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
65 # ... your stuff here ...
66 end
ea1b9f6 @sunaku indent paragraphs beginning with defn-indent line
authored
67
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
68 engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
69 your_roff_output = engine.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
70
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
71 ------------------------------------------------------------------------------
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
72 Document Format
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
73 ------------------------------------------------------------------------------
22daadf @vmg Add sample Manpage renderer
vmg authored
74
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
75 md2man introduces the following additions to the core [Markdown] language:
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
76
77 * If a paragraph's first or subsequent lines are uniformly indented by two
78 spaces, then it is considered to be a "tagged paragraph" and its body is
79 unindented before being emitted under a `.TP` macro in the [Roff] output.
80
81 For example, the following [Markdown] input:
82
83 This is a
84 normal paragraph.
85
86 This is a
87 tagged paragraph.
88
89 This is another
90 tagged paragraph.
91
92 This is yet another
93 tagged paragraph.
94
95 This
96 is another
97 normal
98 paragraph.
99
100 Yields the following [Roff] output:
101
102 .PP
103 This is a
104 normal paragraph.
105 .TP
106 This is a
107 tagged paragraph.
108 .TP
109 This is another
110 tagged paragraph.
111 .TP
112 This is yet another
113 tagged paragraph.
114 .PP
115 This
116 is another
117 normal
118 paragraph.
119
120 Which appears like the following:
121
122 >This is a
123 >normal paragraph.
124 >
125 >>This is a
126 >>tagged paragraph.
127 >
128 >>This is another
129 >>tagged paragraph.
130 >
131 >>This is yet another
132 >>tagged paragraph.
133 >
134 >This
135 > is another
136 > normal
137 > paragraph.
22daadf @vmg Add sample Manpage renderer
vmg authored
138
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
139 ------------------------------------------------------------------------------
140 Limitations
141 ------------------------------------------------------------------------------
22daadf @vmg Add sample Manpage renderer
vmg authored
142
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
143 At present, md2man does not translate the following [Redcarpet2] node types:
22daadf @vmg Add sample Manpage renderer
vmg authored
144
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
145 * `block_html`
146 * `strikethrough`
147 * `superscript`
148 * `image`
149 * `raw_html`
22daadf @vmg Add sample Manpage renderer
vmg authored
150
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
151 It issues a warning when it encounters these instead. Patches are welcome!
22daadf @vmg Add sample Manpage renderer
vmg authored
152
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
153 ------------------------------------------------------------------------------
154 License
155 ------------------------------------------------------------------------------
22daadf @vmg Add sample Manpage renderer
vmg authored
156
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
157 Released under the ISC license. See the LICENSE file for details.
Something went wrong with that request. Please try again.