kramdown-man 0.1.9 → 1.0.1

data/man/kramdown-man.1

@@ -1,133 +1,197 @@
-.\" Generated by kramdown-man 0.1.9
+.\" Generated by kramdown-man 1.0.0
 .\" https://github.com/postmodern/kramdown-man#readme
-.TH kramdown-man.1 "April 2013" kramdown-man "User Manuals"
-.LP
+.TH kramdown-man 1 "April 2013" kramdown-man "User Manuals"
+.SH NAME
+.PP
+kramdown\-man \- generates man pages from markdown files
 .SH SYNOPSIS
-.LP
 .PP
-\fBkramdown-man\fR \[lB]\fIoptions\fP\[rB] <\fIINPUT\fP >\fIOUTPUT\fP
-.LP
+\fBkramdown\-man\fR \[lB]\fIoptions\fP\[rB] \fIMARKDOWN\[ru]FILE\fP
 .SH DESCRIPTION
-.LP
 .PP
 A Kramdown
 .UR http:\[sl]\[sl]kramdown\.gettalong\.org\[sl]
-.UE plugin for converting Markdown files into man pages\.
-.LP
+.UE
+plugin for converting Markdown files into man pages\.
 .SH ARGUMENTS
-.LP
 .TP
-\fIINPUT\fP
+\fIMARKDOWN\[ru]FILE\fP
 The input markdown file to convert\.
-.LP
-.TP
-\fIOUTPUT\fP
-The output file for the man page\.
-.LP
 .SH OPTIONS
-.LP
 .TP
-\fB-h\fR, \fB--help\fR
-Prints the usage for \fBkramdown-man\fR\.
-.LP
+\fB\-o\fR, \fB\-\-output\fR \fIOUTPUT\fP
+The file to write the man page output to\.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Prints the \fBkramdown\-man\fR version\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Prints the usage for \fBkramdown\-man\fR\.
 .SH EXAMPLE
-.LP
-.nf
+.PP
+Render a man page from markdown:
+.PP
+.RS 4
+.EX
+\[Do] kramdown\-man \-o man\[sl]myprogram\.1 man\[sl]myprogram\.1\.md
+.EE
+.RE
+.PP
+Preview the rendered man page:
+.PP
+.RS 4
+.EX
+\[Do] kramdown\-man man\[sl]myprogram\.1\.md
+.EE
+.RE
+.SS RUBY
+.PP
+.RS 4
+.EX
 require \(aqkramdown\(aq
 require \(aqkramdown\[sl]man\(aq
 
 doc \[eq] Kramdown::Document\.new(File\.read(\(aqman\[sl]kramdown\-man\.1\.md\(aq))
 File\.write(\(aqman\[sl]kramdown\-man\.1\(aq,doc\.to\[ru]man)
 system \(aqman\(aq, \(aqman\[sl]kramdown\-man\.1\(aq
-.fi
-.LP
+.EE
+.RE
+.SS RAKE TASK
+.PP
+Define a \fBman\fR and files tasks which render all \fB*\.md\fR files within the
+\fBman\[sl]\fR directory:
+.PP
+.RS 4
+.EX
+require \(aqkramdown\[sl]man\[sl]task\(aq
+Kramdown::Man::Task\.new
+.EE
+.RE
 .SH SYNTAX
-.LP
-.SS FORMATTING
-.LP
-.nf
+.SS Code
+.PP
+.RS 4
+.EX
 \`code\`
-.fi
-.LP
+.EE
+.RE
 .PP
 \fBcode\fR
-.LP
-.nf
+.SS Emphasis
+.PP
+.RS 4
+.EX
 *emphasis*
-.fi
-.LP
+.EE
+.RE
 .PP
 \fIemphasis\fP
-.LP
-.nf
+.SS Strong
+.PP
+.RS 4
+.EX
 **strong**
-.fi
-.LP
+.EE
+.RE
 .PP
 \fBstrong\fP
-.LP
-.SS PARAGRAPHS
-.LP
-.nf
+.SS Paragraph
+.PP
+.RS 4
+.EX
 Normal paragraph\.
-.fi
-.LP
+.EE
+.RE
 .PP
 Normal paragraph\.
-.LP
-.nf
+.SS Usage String
+.PP
+.RS 4
+.EX
 \`command\` \[lB]\`\-\-foo\`\[rB] **FILE**
-.fi
-.LP
-.PP
-\fBcommand\fR \[lB]\fB--foo\fR\[rB] \fBFILE\fP
-.LP
-.nf
-\`\-\-tagged\`
-  Text here\.
-.fi
-.LP
+.EE
+.RE
+.PP
+\fBcommand\fR \[lB]\fB\-\-foo\fR\[rB] \fBFILE\fP
+.SS Argument Definitions
+.PP
+.RS 4
+.EX
+*ARG*
+: Description here\.
+.EE
+.RE
+.TP
+\fIARG\fP
+Description here\.
+.SS Option Definitions
+.PP
+.RS 4
+.EX
+\`\-o\`, \`\-\-option\` *VALUE*
+: Description here\.
+.EE
+.RE
 .TP
-\fB--tagged\fR
-Text here\.
-.LP
-.SS LINKS
-.LP
-.nf
+\fB\-o\fR, \fB\-\-option\fR \fIVALUE\fP
+Description here\.
+.SS Links
+.PP
+.RS 4
+.EX
 \[lB]website\[rB](http:\[sl]\[sl]example\.com\[sl])
-.fi
-.LP
+.EE
+.RE
 .PP
 website
 .UR http:\[sl]\[sl]example\.com\[sl]
 .UE
-.LP
-.nf
+.SS Man Pages
+.PP
+Link to other man pages in a project:
+.PP
+.RS 4
+.EX
+\[lB]kramdown\-man\[rB](kramdown\-man\.1\.md)
+.EE
+.RE
+.PP
+.BR kramdown\-man (1)
+.PP
+Link to other system man page:
+.PP
+.RS 4
+.EX
 \[lB]bash\[rB](man:bash(1))
-.fi
-.LP
+.EE
+.RE
 .PP
 .BR bash (1)
-.LP
-.nf
+.PP
+\fBNote:\fP only works on firefox
+.UR https:\[sl]\[sl]www\.mozilla\.org\[sl]en\-US\[sl]firefox\[sl]new\[sl]
+.UE
+on Linux\.
+.SS Email Addresses
+.PP
+.RS 4
+.EX
 Email <bob\[at]example\.com>
-.fi
-.LP
+.EE
+.RE
 .PP
 Email 
 .MT bob\[at]example\.com
 .ME
-.LP
-.SS LISTS
-.LP
-.nf
+.SS Lists
+.PP
+.RS 4
+.EX
 * one
 * two
 * three
-
-  extra paragraph
-.fi
-.LP
+.EE
+.RE
 .RS
 .IP \(bu 2
 one
@@ -135,10 +199,16 @@ one
 two
 .IP \(bu 2
 three
-.IP \( 2
-extra paragraph
 .RE
-.LP
+.SS Numbered Lists
+.PP
+.RS 4
+.EX
+1\. one
+2\. two
+3\. three
+.EE
+.RE
 .nr step1 0 1
 .RS
 .IP \n+[step1]
@@ -147,43 +217,51 @@ one
 two
 .IP \n+[step1]
 three
-.IP \n
-extra paragraph
-.RE
-.LP
-.SS HORIZONTAL RULE
-.LP
-.nf
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-.fi
-.LP
-.ti 0
-\l'\n(.lu'
-.LP
-.SS BLOCKQUOTES
-.LP
-.nf
+.RE
+.SS Definition Lists
+.PP
+.RS 4
+.EX
+ex\[pc]am\[pc]ple
+: a thing characteristic of its kind or illustrating a general rule\.
+
+: a person or thing regarded in terms of their fitness to be imitated or the
+  likelihood of their being imitated\.
+.EE
+.RE
+.TP
+ex\[pc]am\[pc]ple
+a thing characteristic of its kind or illustrating a general rule\.
+.RS
+.PP
+a person or thing regarded in terms of their fitness to be imitated or the
+likelihood of their being imitated\.
+.RE
+.SS Blockquotes
+.PP
+.RS 4
+.EX
 > Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away\.
 >
 > \-\-Antoine de Saint\-Exup\['e]ry
-.fi
-.LP
-.PP
+.EE
+.RE
 .RS
+.PP
 Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away\.
-.LP
+.PP
 \-\-Antoine de Saint\-Exup\['e]ry
 .RE
-.LP
-.SS CODE BLOCKS
-.LP
-.nf
+.SS Code Blocks
+.PP
+.RS 4
+.EX
     \[sh]include <stdio\.h>
 
     int main()
     \[lC]
-	    printf(\[dq]hello world\en\[dq]);
-	    return 0;
+        printf(\[dq]hello world\en\[dq]);
+        return 0;
     \[rC]
 
 \[sh]include <stdio\.h>
@@ -193,12 +271,26 @@ int main()
     printf(\[dq]hello world\en\[dq]);
     return 0;
 \[rC]
-.fi
-.LP
+.EE
+.RE
+.SS Code Fences
+.PP
+.RS 4
+.EX
+\`\`\`
+puts \[dq]hello world\[dq]
+\`\`\`
+.EE
+.RE
+.PP
+.PP
+.RS 4
+.EX
+puts \[dq]hello world\[dq]
+.EE
+.RE
 .SH AUTHOR
-.LP
 .PP
 Postmodern 
 .MT postmodern\.mod3\[at]gmail\.com
 .ME
-.LP

data/man/kramdown-man.1.md

@@ -1,8 +1,12 @@
-# kramdown-man.1 "April 2013" kramdown-man "User Manuals"
+# kramdown-man 1 "April 2013" kramdown-man "User Manuals"
+
+## NAME
+
+kramdown-man - generates man pages from markdown files
 
 ## SYNOPSIS
 
-`kramdown-man` [*options*] \<*INPUT* \>*OUTPUT*
+`kramdown-man` [*options*] *MARKDOWN_FILE*
 
 ## DESCRIPTION
 
@@ -10,19 +14,32 @@ A [Kramdown][kramdown] plugin for converting Markdown files into man pages.
 
 ## ARGUMENTS
 
-*INPUT*
-    The input markdown file to convert.
-
-*OUTPUT*
-    The output file for the man page.
+*MARKDOWN_FILE*
+: The input markdown file to convert.
 
 ## OPTIONS
 
+`-o`, `--output` *OUTPUT*
+: The file to write the man page output to.
+
+`-V`, `--version`
+: Prints the `kramdown-man` version.
+
 `-h`, `--help`
-    Prints the usage for `kramdown-man`.
+: Prints the usage for `kramdown-man`.
 
 ## EXAMPLE
 
+Render a man page from markdown:
+
+    $ kramdown-man -o man/myprogram.1 man/myprogram.1.md
+
+Preview the rendered man page:
+
+    $ kramdown-man man/myprogram.1.md
+
+### RUBY
+
     require 'kramdown'
     require 'kramdown/man'
 
@@ -30,86 +47,127 @@ A [Kramdown][kramdown] plugin for converting Markdown files into man pages.
     File.write('man/kramdown-man.1',doc.to_man)
     system 'man', 'man/kramdown-man.1'
 
+### RAKE TASK
+
+Define a `man` and files tasks which render all `*.md` files within the
+`man/` directory:
+
+    require 'kramdown/man/task'
+    Kramdown::Man::Task.new
+
 ## SYNTAX
 
-### FORMATTING
+### Code
 
     `code`
 
 `code`
 
+### Emphasis
+
     *emphasis*
 
 *emphasis*
 
+### Strong
+
     **strong**
 
 **strong**
 
-### PARAGRAPHS
+### Paragraph
 
     Normal paragraph.
 
 Normal paragraph.
 
+#### Usage String
+
     `command` [`--foo`] **FILE**
 
 `command` [`--foo`] **FILE**
 
-    `--tagged`
-      Text here.
+#### Argument Definitions
+
+    *ARG*
+    : Description here.
 
-`--tagged`
-  Text here.
+*ARG*
+: Description here.
 
-### LINKS
+#### Option Definitions
+
+    `-o`, `--option` *VALUE*
+    : Description here.
+
+`-o`, `--option` *VALUE*
+: Description here.
+
+### Links
 
     [website](http://example.com/)
 
 [website](http://example.com/)
 
+#### Man Pages
+
+Link to other man pages in a project:
+
+    [kramdown-man](kramdown-man.1.md)
+
+[kramdown-man](kramdown-man.1.md)
+
+Link to other system man page:
+
     [bash](man:bash(1))
 
 [bash](man:bash(1))
 
+**Note:** only works on [firefox] on Linux.
+
+[firefox]: https://www.mozilla.org/en-US/firefox/new/
+
+#### Email Addresses
+
     Email <bob@example.com>
 
 Email <bob@example.com>
 
-### LISTS
+### Lists
 
     * one
     * two
     * three
-    
-      extra paragraph
-    
 
 * one
 * two
 * three
 
-  extra paragraph
+#### Numbered Lists
 
     1. one
     2. two
     3. three
-    
-       extra paragraph
-    
+
 1. one
 2. two
 3. three
 
-   extra paragraph
+#### Definition Lists
+
+    ex·am·ple
+    : a thing characteristic of its kind or illustrating a general rule.
 
-### HORIZONTAL RULE
+    : a person or thing regarded in terms of their fitness to be imitated or the
+      likelihood of their being imitated.
 
-    -------------------------------------------------------------------------------
+ex·am·ple
+: a thing characteristic of its kind or illustrating a general rule.
 
--------------------------------------------------------------------------------
+: a person or thing regarded in terms of their fitness to be imitated or the
+  likelihood of their being imitated.
 
-### BLOCKQUOTES
+### Blockquotes
 
     > Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
     >
@@ -119,14 +177,14 @@ Email <bob@example.com>
 >
 > --Antoine de Saint-Exupéry
 
-### CODE BLOCKS
+### Code Blocks
 
         #include <stdio.h>
-    
+
         int main()
         {
-    	    printf("hello world\n");
-    	    return 0;
+            printf("hello world\n");
+            return 0;
         }
 
     #include <stdio.h>
@@ -137,6 +195,16 @@ Email <bob@example.com>
 	    return 0;
     }
 
+#### Code Fences
+
+    ```
+    puts "hello world"
+    ```
+
+```
+puts "hello world"
+```
+
 ## AUTHOR
 
 Postmodern <postmodern.mod3@gmail.com>