README.md in kramdown-man-0.1.9 vs README.md in kramdown-man-1.0.0
- old
+ new
@@ -1,7 +1,11 @@
# kramdown-man
+[](https://github.com/postmodern/kramdown-man/actions/workflows/ruby.yml)
+[](https://codeclimate.com/github/postmodern/kramdown-man)
+[](https://badge.fury.io/rb/kramdown-man)
+
* [Homepage](https://github.com/postmodern/kramdown-man#readme)
* [Issues](https://github.com/postmodern/kramdown-man/issues)
* [Documentation](http://rubydoc.info/gems/kramdown-man/frames)
## Description
@@ -9,157 +13,251 @@
A [Kramdown][kramdown] convert for converting Markdown files into man pages.
## Features
* Converts markdown to [roff]:
- * Supports codespans, emphasis and strong fonts.
- * Supports normal, hanging and tagged paragraphs.
- * Supports bullet lists.
+ * Supports codespans, emphasis, and strong fonts.
+ * Supports normal and tagged paragraphs.
+ * Supports codeblocks and blockquotes.
+ * Supports bullet, numbered, and definition lists.
* Supports multi-paragraph list items and blockquotes.
- * Supports horizontal rules.
- * Supports converting `[bash](man:bash(1))` and `[bash](man:bash.1)` links
- into man page references.
+ * Supports converting `[foo-bar](foo-bar.1.md)` and `[bash](man:bash(1))`
+ links into `SEE ALSO` man page references.
* Provides Rake task for converting `man/*.md` into man pages.
* Uses the pure-Ruby [Kramdown][kramdown] markdown parser.
* Supports [Ruby] 3.x, [JRuby], and [TruffleRuby].
## Synopsis
+```
+usage: kramdown-man [options] MARKDOWN_FILE
+ -o, --output FILE Write the man page output to the file
+ -V, --version Print the version
+ -h, --help Print the help output
+
+Examples:
+ kramdown-man -o man/myprogram.1 man/myprogram.1.md
+ kramdown-man man/myprogram.1.md
+
+```
+
Render a man page from markdown:
- $ kramdown-man <man/myprog.1.md >man/myprog.1
+```shell
+kramdown-man -o man/myprogram.1 man/myprogram.1.md
+```
+Preview the rendered man page:
+
+```shell
+kramdown-man man/myprogram.1.md
+```
+
## Examples
Render a man page from a markdown file:
- require 'kramdown/man'
+```ruby
+require 'kramdown/man'
- doc = Kramdown::Document.new(File.read('man/kramdown-man.1.md'))
- File.write('man/kramdown-man.1',doc.to_man)
+doc = Kramdown::Document.new(File.read('man/kramdown-man.1.md'))
+File.write('man/kramdown-man.1',doc.to_man)
- system 'man', 'man/kramdown-man.1'
+system 'man', 'man/kramdown-man.1'
+```
Define a `man` and file tasks which render all `*.md` files within the
`man/` directory:
- require 'kramdown/man/task'
- Kramdown::Man::Task.new
+```ruby
+require 'kramdown/man/task'
+Kramdown::Man::Task.new
+```
## Syntax
-### Formatting
+### Code
- `code`
+```markdown
+`code`
+```
`code`
- *emphasis*
+### Emphasis
+```markdown
*emphasis*
+```
- **strong**
+*emphasis*
+### Strong
+
+```markdown
**strong**
+```
-### Paragraphs
+**strong**
- Normal paragraph.
+### Paragraph
+```markdown
Normal paragraph.
+```
- `command` [`--foo`] **FILE**
+Normal paragraph.
+#### Usage String
+
+```markdown
`command` [`--foo`] **FILE**
+```
- `--tagged`
- Text here.
+`command` [`--foo`] **FILE**
-`--tagged`
- Text here.
+#### Argument Definitions
+```markdown
+*ARG*
+: Description here.
+```
+
+*ARG*
+: Description here.
+
+#### Option Definitions
+
+```markdown
+`-o`, `--option` *VALUE*
+: Description here.
+```
+
+`-o`, `--option` *VALUE*
+: Description here.
+
### Links
- [website](http://example.com/)
+```markdown
+[website](http://example.com/)
+```
[website](http://example.com/)
- [bash](man:bash(1))
+#### Man Pages
+Link to other man pages in a project:
+
+```markdown
+[kramdown-man](kramdown-man.1.md)
+```
+
+[kramdown-man](https://github.com/postmodern/kramdown-man/blob/main/man/kramdown-man.1.md)
+
+Link to other system man page:
+
+```markdown
[bash](man:bash(1))
+```
- Email <bob@example.com>
+[bash](man:bash(1))
+**Note:** only works on [firefox] on Linux.
+
+[firefox]: https://www.mozilla.org/en-US/firefox/new/
+
+#### Email Addresses
+
+```markdown
Email <bob@example.com>
+```
+Email <bob@example.com>
+
### Lists
- * one
- * two
- * three
-
- extra paragraph
-
+```markdown
+* one
+* two
+* three
+```
* one
* two
* three
- extra paragraph
+#### Numbered Lists
- 1. one
- 2. two
- 3. three
+```markdown
+1. one
+2. two
+3. three
+```
- extra paragraph
-
1. one
2. two
3. three
- extra paragraph
+#### Definition Lists
-### Horizontal Rule
+```markdown
+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.
+```
--------------------------------------------------------------------------------
+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
- > Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
- >
- > --Antoine de Saint-Exupéry
+```markdown
+> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
+>
+> --Antoine de Saint-Exupéry
+```
> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
>
> --Antoine de Saint-Exupéry
### Code Blocks
- #include <stdio.h>
-
- int main()
- {
- printf("hello world\n");
- return 0;
- }
+```markdown
+Source code:
#include <stdio.h>
int main()
{
+ printf("hello world\n");
+ return 0;
+ }
+
+```
+
+Source code:
+
+ #include <stdio.h>
+
+ int main()
+ {
printf("hello world\n");
return 0;
}
## Requirements
* [kramdown] ~> 2.0
## Install
- $ gem install kramdown-man
+```shell
+gem install kramdown-man
+```
## Alternatives
* [Redcarpet::Render::ManPage](http://rubydoc.info/gems/redcarpet/Redcarpet/Render/ManPage)
* [ronn](https://github.com/rtomayko/ronn#readme)