Permalink
Browse files

README: mention features; revise markdown; cleanup

  • Loading branch information...
1 parent d783b42 commit 5f4091cd17b049eb10bc7bce7a9217c6554d9ea2 @sunaku committed Feb 4, 2012
Showing with 70 additions and 85 deletions.
  1. +11 −19 HISTORY.markdown
  2. +37 −38 README.markdown
  3. +14 −20 bin/md2man
  4. +8 −8 md2man.gemspec
View
@@ -1,13 +1,11 @@
-------------------------------------------------------------------------------
-Version 1.1.0 (2012-02-02)
-------------------------------------------------------------------------------
+## Version 1.1.0 (2012-02-02)
-Improvements:
+Minor:
* Add `Md2Man::Document` module for programmatic processing of
cross-references to other UNIX manual pages within Redcarpet.
-Housekeeping:
+Other:
* README: not all systems support `man -l` option.
@@ -19,29 +17,25 @@ Housekeeping:
* README: simplify project slogan to be more memorable.
-------------------------------------------------------------------------------
-Version 1.0.2 (2012-01-09)
-------------------------------------------------------------------------------
+## Version 1.0.2 (2012-01-09)
-Corrections:
+Patch:
* Blockquote's leading paragraph regexp was not anchored.
* Freezing internal constants prevents monkey patching.
-Housekeeping:
+Other:
* Upgraded to Binman 3 for better interoperability with Bundler.
* Added example input file from the Linux Man Page Howto.
* Forgot to change project slogan in the gem package.
-------------------------------------------------------------------------------
-Version 1.0.1 (2011-12-06)
-------------------------------------------------------------------------------
+## Version 1.0.1 (2011-12-06)
-Divergences:
+Major:
* Renamed the project from "redcarpet-manpage" to "md2man".
@@ -52,7 +46,7 @@ Divergences:
* Tagged paragraphs no longer require the first line to begin with italic or
bold styling. All that matters is that the subsequent lines are indented.
-Improvements:
+Minor:
* Added md2man(1) executable for command-line usage.
@@ -64,12 +58,10 @@ Improvements:
* Improved README with some new and revised documentation.
-Housekeeping:
+Other:
* Rewrote entire Markdown to Roff conversion from scratch while doing TDD.
-------------------------------------------------------------------------------
-Version 0.0.1 (2011-10-13)
-------------------------------------------------------------------------------
+## Version 0.0.1 (2011-10-13)
First release! Happy birthday! Woohoo! :-)
View
@@ -1,27 +1,40 @@
-md2man - markdown to manpage
-==============================================================================
+# md2man - markdown to manpage
md2man is a Ruby library and command-line program that converts [Markdown]
-documents into UNIX man pages (really [Roff] documents) using [Redcarpet2].
+documents into UNIX man pages (really [Roff] documents) using [Redcarpet].
-[Roff]: http://troff.org
-[Markdown]: http://daringfireball.net/projects/markdown/
-[Redcarpet2]: https://github.com/tanoku/redcarpet
-[example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
+## Features
+
+ * Formats tagged and indented paragraphs (see "document format" below).
-------------------------------------------------------------------------------
-Demonstration
-------------------------------------------------------------------------------
+ * Translates all HTML4 and XHTML1 entities into native Roff equivalents.
+
+ * Supports markdown extensions such as [PHP Markdown Extra tables][tables].
+
+ * Usable from the command line as a filter in a UNIX pipeline.
+
+### Demonstration
Try converting [this example Markdown file][example] into a UNIX man page:
- md2man EXAMPLE.markdown > EXAMPLE.man && man ./EXAMPLE.man
+ md2man EXAMPLE.markdown > EXAMPLE.1
+ man EXAMPLE.1
![Obligatory screenshot of md2man(1) in action!](http://ompldr.org/vYnFvbw)
-------------------------------------------------------------------------------
-Installation
-------------------------------------------------------------------------------
+### Limitations
+
+At present, md2man does not translate the following [Redcarpet] node types:
+
+ * `block_html`
+ * `strikethrough`
+ * `superscript`
+ * `image`
+ * `raw_html`
+
+It issues a warning when it encounters these instead. Patches are welcome!
+
+## Installation
gem install md2man
@@ -33,9 +46,7 @@ Installation
bundle_bin/md2man --help # run it directly
bundle exec rake -T # packaging tasks
-------------------------------------------------------------------------------
-Usage
-------------------------------------------------------------------------------
+## Usage
### At the command line
@@ -77,11 +88,9 @@ Mix-in your own renderer:
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
your_roff_output = engine.render(your_markdown_input)
-------------------------------------------------------------------------------
-Document format
-------------------------------------------------------------------------------
+### Document format
-md2man attaches the following additional semantics to its [Markdown] input:
+md2man applies the following additional semantics to its [Markdown] input:
* There can be at most one top-level heading (H1). It is emitted as `.TH`
in the [Roff] output, specifying the UNIX man page's header and footer.
@@ -94,22 +103,12 @@ md2man attaches the following additional semantics to its [Markdown] input:
indented by two spaces are considered to be a "tagged paragraphs". They
are unindented accordingly before emission as `.TP` in the [Roff] output.
-------------------------------------------------------------------------------
-Known issues
-------------------------------------------------------------------------------
-
-At present, md2man does not translate the following [Redcarpet2] node types:
-
- * `block_html`
- * `strikethrough`
- * `superscript`
- * `image`
- * `raw_html`
-
-It issues a warning when it encounters these instead. Patches are welcome!
-
-------------------------------------------------------------------------------
-License
-------------------------------------------------------------------------------
+## License
Released under the ISC license. See the LICENSE file for details.
+
+[Roff]: http://troff.org
+[Markdown]: http://daringfireball.net/projects/markdown/
+[Redcarpet]: https://github.com/tanoku/redcarpet
+[example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
+[tables]: http://michelf.com/projects/php-markdown/extra/#table
View
@@ -1,29 +1,25 @@
#!/usr/bin/env ruby
-=begin
+=begin =======================================================================
-MD2MAN 1 "2012-02-02" "1.1.0"
-=============================
+# MD2MAN 1 "2012-02-02" "1.1.0"
-NAME
-----
+## NAME
md2man - convert markdown(7) into roff(7)
-SYNOPSIS
---------
+## SYNOPSIS
`md2man` [*OPTION*]... [*FILE*]
-DESCRIPTION
------------
+## DESCRIPTION
[md2man] converts markdown(7) input from the given *FILE* into roff(7) using
-[Redcarpet2] and then prints the result to the standard output stream. If
+[Redcarpet] and then prints the result to the standard output stream. If
*FILE* is not given, then the standard input stream is read in its place.
-### Document Format
+### Document format
-The following additional semantics are attached to markdown(7):
+The following additional semantics are applied to the markdown(7) input:
* There can be at most one top-level heading (H1). It is emitted as `.TH`
in the roff(7) output, specifying the UNIX man page's header and footer.
@@ -36,9 +32,9 @@ The following additional semantics are attached to markdown(7):
indented by two spaces are considered to be a "tagged paragraphs". They
are unindented accordingly before emission as `.TP` in the roff(7) output.
-### Markdown Extensions
+### Markdown extensions
-The following [Redcarpet2] extensions for markdown(7) are enabled:
+The following [Redcarpet] extensions for markdown(7) are enabled:
* tables
* autolink
@@ -47,19 +43,17 @@ The following [Redcarpet2] extensions for markdown(7) are enabled:
* no_intra_emphasis
* fenced_code_blocks
-OPTIONS
--------
+## OPTIONS
`-h`, `--help`
- Display this help manual using man(1).
+ Show this help manual.
-SEE ALSO
---------
+## SEE ALSO
markdown(7), roff(7)
[md2man]: https://github.com/sunaku/md2man
-[Redcarpet2]: https://github.com/tanoku/redcarpet
+[Redcarpet]: https://github.com/tanoku/redcarpet
=end =========================================================================
View
@@ -1,20 +1,20 @@
# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "md2man/version"
+$:.push File.expand_path('../lib', __FILE__)
+require 'md2man/version'
Gem::Specification.new do |s|
- s.name = "md2man"
+ s.name = 'md2man'
s.version = Md2Man::VERSION
s.authors,
s.email = File.read('LICENSE').scan(/Copyright \d+ (.+) <(.+?)>/).transpose
- s.homepage = "http://github.com/sunaku/md2man"
- s.summary = "Markdown to manpage."
- s.description = "Write UNIX man pages in Markdown."
+ s.homepage = 'http://github.com/sunaku/md2man'
+ s.summary = 'markdown to manpage'
+ s.description = 'Converts markdown documents into UNIX man pages (roff).'
- s.files = `git ls-files`.split("\n") + Dir["man/**/*"]
+ s.files = `git ls-files`.split("\n") + Dir['man/**/*']
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
- s.require_paths = ["lib"]
+ s.require_paths = ['lib']
s.add_runtime_dependency 'binman', '~> 3'
s.add_runtime_dependency 'redcarpet', '>= 2.1.0', '< 3'

0 comments on commit 5f4091c

Please sign in to comment.