Skip to content
Newer
Older
100644 118 lines (74 sloc) 3.28 KB
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
1 # md2man - markdown to manpage
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
2
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 6, 2011
3 md2man is a Ruby library and command-line program that converts [Markdown]
821fb97 Version 1.2.0
Suraj N. Kurapati authored Feb 6, 2012
4 documents into UNIX manual pages (really [Roff] documents) using [Redcarpet].
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
5
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
6 ## Features
7
8 * Formats tagged and indented paragraphs (see "document format" below).
5d7df2e add example input file from Linux Man Page Howto
Suraj N. Kurapati authored Dec 7, 2011
9
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
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 add example input file from Linux Man Page Howto
Suraj N. Kurapati authored Dec 7, 2011
17
821fb97 Version 1.2.0
Suraj N. Kurapati authored Feb 6, 2012
18 Try converting [this example Markdown file][example] into a UNIX manual page:
5d7df2e add example input file from Linux Man Page Howto
Suraj N. Kurapati authored Dec 7, 2011
19
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
20 md2man EXAMPLE.markdown > EXAMPLE.1
21 man EXAMPLE.1
5d7df2e add example input file from Linux Man Page Howto
Suraj N. Kurapati authored Dec 7, 2011
22
23 ![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
24
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
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 Aug 4, 2011
38
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
39 gem install md2man
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
40
c010956 README: fix installation commands for development
Suraj N. Kurapati authored Jan 26, 2012
41 ### Development
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
42
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
43 git clone git://github.com/sunaku/md2man
44 cd md2man
c010956 README: fix installation commands for development
Suraj N. Kurapati authored Jan 26, 2012
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 Aug 4, 2011
48
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
49 ## Usage
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
50
628f392 Version 1.1.0
Suraj N. Kurapati authored Feb 2, 2012
51 ### At the command line
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
52
53 md2man --help
54
821fb97 Version 1.2.0
Suraj N. Kurapati authored Feb 6, 2012
55 ### Inside a Ruby script
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
56
432cfdf rename project to Redman; rewrite from scratch
Suraj N. Kurapati authored Nov 5, 2011
57 Use the default renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
58
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
59 require 'md2man'
04d3feb capitalize the "man" in Md2Man for great honor
Suraj N. Kurapati authored Dec 6, 2011
60 your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
61
24ef16c split Roff into a module mixin and an Engine class
Suraj N. Kurapati authored Dec 6, 2011
62 Build your own renderer:
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
63
fb220e4 rename project to "md2man": better reflect purpose
Suraj N. Kurapati authored Dec 7, 2011
64 require 'md2man'
04d3feb capitalize the "man" in Md2Man for great honor
Suraj N. Kurapati authored Dec 7, 2011
65 engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash)
24ef16c split Roff into a module mixin and an Engine class
Suraj N. Kurapati authored Dec 7, 2011
66 your_roff_output = engine.render(your_markdown_input)
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
67
24ef16c split Roff into a module mixin and an Engine class
Suraj N. Kurapati authored Dec 7, 2011
68 Define your own renderer:
69
70 require 'md2man'
71
04d3feb capitalize the "man" in Md2Man for great honor
Suraj N. Kurapati authored Dec 7, 2011
72 class YourManpageRenderer < Md2Man::Engine
24ef16c split Roff into a module mixin and an Engine class
Suraj N. Kurapati authored Dec 7, 2011
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 capitalize the "man" in Md2Man for great honor
Suraj N. Kurapati authored Dec 7, 2011
84 include Md2Man::Roff
432cfdf rename project to Redman; rewrite from scratch
Suraj N. Kurapati authored Nov 5, 2011
85 # ... your stuff here ...
86 end
ea1b9f6 indent paragraphs beginning with defn-indent line
Suraj N. Kurapati authored Nov 2, 2011
87
24ef16c split Roff into a module mixin and an Engine class
Suraj N. Kurapati authored Dec 7, 2011
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 Aug 4, 2011
90
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
91 ### Document format
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
92
821fb97 Version 1.2.0
Suraj N. Kurapati authored Feb 6, 2012
93 md2man extends [Markdown] syntax in the following ways, as provisioned in the
94 `Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
1c3324b explain the role of top-level H1 headings
Suraj N. Kurapati authored Dec 6, 2011
95
475797b indented paragraphs != tagged paragraphs
Suraj N. Kurapati authored Dec 6, 2011
96 * Paragraphs whose lines are all uniformly indented by two spaces are
97 considered to be "indented paragraphs". They are unindented accordingly
98 before emission as `.IP` in the [Roff] output.
99
100 * Paragraphs whose subsequent lines (all except the first) are uniformly
101 indented by two spaces are considered to be a "tagged paragraphs". They
102 are unindented accordingly before emission as `.TP` in the [Roff] output.
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
103
821fb97 Version 1.2.0
Suraj N. Kurapati authored Feb 6, 2012
104 md2man extends [Markdown] semantics in the following ways:
105
106 * There can be at most one top-level heading (H1). It is emitted as `.TH`
107 in the [Roff] output, defining the UNIX manual page's header and footer.
108
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
109 ## License
22daadf @vmg Add sample Manpage renderer
vmg authored Aug 4, 2011
110
30fae24 combine: Redcarpet2 + BinMan => redcarpet-manpage
Suraj N. Kurapati authored Oct 13, 2011
111 Released under the ISC license. See the LICENSE file for details.
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
112
113 [Roff]: http://troff.org
114 [Markdown]: http://daringfireball.net/projects/markdown/
47c6eac @tanoku changed his username and email on GitHub
Suraj N. Kurapati authored Sep 27, 2012
115 [Redcarpet]: https://github.com/vmg/redcarpet
5f4091c README: mention features; revise markdown; cleanup
Suraj N. Kurapati authored Feb 4, 2012
116 [example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
117 [tables]: http://michelf.com/projects/php-markdown/extra/#table
Something went wrong with that request. Please try again.