Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 115 lines (72 sloc) 3.217 kb
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
1 # md2man - markdown to manpage
22daadf @vmg Add sample Manpage renderer
vmg authored
2
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
3 md2man is a Ruby library and command-line program that converts [Markdown]
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
4 documents into UNIX man pages (really [Roff] documents) using [Redcarpet].
22daadf @vmg Add sample Manpage renderer
vmg authored
5
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
6 ## Features
7
8 * Formats tagged and indented paragraphs (see "document format" below).
5d7df2e @sunaku add example input file from Linux Man Page Howto
authored
9
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
10 * Translates all HTML4 and XHTML1 entities into native Roff equivalents.
11
12 * Supports markdown extensions such as [PHP Markdown Extra tables][tables].
13
14 * Usable from the command line as a filter in a UNIX pipeline.
15
16 ### Demonstration
5d7df2e @sunaku add example input file from Linux Man Page Howto
authored
17
18 Try converting [this example Markdown file][example] into a UNIX man page:
19
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
20 md2man EXAMPLE.markdown > EXAMPLE.1
21 man EXAMPLE.1
5d7df2e @sunaku add example input file from Linux Man Page Howto
authored
22
23 ![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
22daadf @vmg Add sample Manpage renderer
vmg authored
24
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
25 ### Limitations
26
27 At present, md2man does not translate the following [Redcarpet] node types:
28
29 * `block_html`
30 * `strikethrough`
31 * `superscript`
32 * `image`
33 * `raw_html`
34
35 It issues a warning when it encounters these instead. Patches are welcome!
36
37 ## Installation
22daadf @vmg Add sample Manpage renderer
vmg authored
38
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
39 gem install md2man
22daadf @vmg Add sample Manpage renderer
vmg authored
40
c010956 @sunaku README: fix installation commands for development
authored
41 ### Development
22daadf @vmg Add sample Manpage renderer
vmg authored
42
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
43 git clone git://github.com/sunaku/md2man
44 cd md2man
c010956 @sunaku README: fix installation commands for development
authored
45 bundle install --binstubs=bundle_bin
46 bundle_bin/md2man --help # run it directly
47 bundle exec rake -T # packaging tasks
22daadf @vmg Add sample Manpage renderer
vmg authored
48
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
49 ## Usage
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
50
628f392 @sunaku Version 1.1.0
authored
51 ### At the command line
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
52
53 md2man --help
54
628f392 @sunaku Version 1.1.0
authored
55 ### In your Ruby scripts
22daadf @vmg Add sample Manpage renderer
vmg authored
56
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
57 Use the default renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored
58
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
59 require 'md2man'
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
60 your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
61
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
62 Build your own renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored
63
fb220e4 @sunaku rename project to "md2man": better reflect purpose
authored
64 require 'md2man'
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
65 engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash)
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
66 your_roff_output = engine.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
67
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
68 Define your own renderer:
69
70 require 'md2man'
71
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
72 class YourManpageRenderer < Md2Man::Engine
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
73 # ... your stuff here ...
74 end
75
76 engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
77 your_roff_output = engine.render(your_markdown_input)
78
79 Mix-in your own renderer:
80
81 require 'md2man'
82
83 class YourManpageRenderer < Redcarpet::Render::Base
04d3feb @sunaku capitalize the "man" in Md2Man for great honor
authored
84 include Md2Man::Roff
432cfdf @sunaku rename project to Redman; rewrite from scratch
authored
85 # ... your stuff here ...
86 end
ea1b9f6 @sunaku indent paragraphs beginning with defn-indent line
authored
87
24ef16c @sunaku split Roff into a module mixin and an Engine class
authored
88 engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
89 your_roff_output = engine.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored
90
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
91 ### Document format
22daadf @vmg Add sample Manpage renderer
vmg authored
92
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
93 md2man applies the following additional semantics to its [Markdown] input:
475797b @sunaku indented paragraphs != tagged paragraphs
authored
94
1c3324b @sunaku explain the role of top-level H1 headings
authored
95 * There can be at most one top-level heading (H1). It is emitted as `.TH`
96 in the [Roff] output, specifying the UNIX man page's header and footer.
97
475797b @sunaku indented paragraphs != tagged paragraphs
authored
98 * Paragraphs whose lines are all uniformly indented by two spaces are
99 considered to be "indented paragraphs". They are unindented accordingly
100 before emission as `.IP` in the [Roff] output.
101
102 * Paragraphs whose subsequent lines (all except the first) are uniformly
103 indented by two spaces are considered to be a "tagged paragraphs". They
104 are unindented accordingly before emission as `.TP` in the [Roff] output.
22daadf @vmg Add sample Manpage renderer
vmg authored
105
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
106 ## License
22daadf @vmg Add sample Manpage renderer
vmg authored
107
30fae24 @sunaku combine: Redcarpet2 + BinMan => redcarpet-manpage
authored
108 Released under the ISC license. See the LICENSE file for details.
5f4091c @sunaku README: mention features; revise markdown; cleanup
authored
109
110 [Roff]: http://troff.org
111 [Markdown]: http://daringfireball.net/projects/markdown/
112 [Redcarpet]: https://github.com/tanoku/redcarpet
113 [example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
114 [tables]: http://michelf.com/projects/php-markdown/extra/#table
Something went wrong with that request. Please try again.