md2man 1.6.2 → 2.0.0

data/README.markdown

@@ -1,7 +1,7 @@
 # md2man - markdown to manpage
 
-md2man is a Ruby library and command-line program that converts [Markdown]
-documents into UNIX manual pages (both [roff] and HTML) using [Redcarpet].
+md2man is a Ruby library and a set of command-line programs that convert
+[Markdown] into UNIX manual pages (both [roff] and HTML) using [Redcarpet].
 
 ## Features
 
@@ -11,29 +11,22 @@ documents into UNIX manual pages (both [roff] and HTML) using [Redcarpet].
 
   * Supports markdown extensions such as [PHP Markdown Extra tables][tables].
 
-  * Usable from the command line as a filter in a UNIX pipeline.
+  * Usable from the command line as a filter in a UNIX command pipeline.
 
 ### Demonstration
 
 Try converting [this example Markdown file][example] into a UNIX manual page:
 
-    md2man EXAMPLE.markdown > EXAMPLE.1
+    md2man-roff EXAMPLE.markdown > EXAMPLE.1
     man -l EXAMPLE.1
 
 ![Obligatory screenshot of md2man(1) in action!](
 https://raw.github.com/sunaku/md2man/master/EXAMPLE.png)
 
-### Limitations
+Also try converting [that example Markdown file][example] into a web page:
 
-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!
+    md2man-html EXAMPLE.markdown > EXAMPLE.html
+    open EXAMPLE.html
 
 ## Installation
 
@@ -44,56 +37,40 @@ It issues a warning when it encounters these instead.  Patches are welcome!
     git clone git://github.com/sunaku/md2man
     cd md2man
     bundle install
-    bundle exec md2man --help  # run it directly
-    bundle exec rake --tasks   # packaging tasks
+    bundle exec rake --tasks        # packaging tasks
+    bundle exec md2man-roff --help  # run it directly
+    bundle exec md2man-html --help  # run it directly
 
 ## Usage
 
-### Document format
-
-md2man extends [Markdown] syntax in the following ways, as provisioned in the
-`Md2Man::Document` module and defined in its derivative `Md2Man::Roff` module:
-
-  * Paragraphs whose lines are all uniformly indented by two spaces are
-    considered to be "indented paragraphs".  They are unindented accordingly
-    before emission as `.IP` in the [roff] output.
-
-  * Paragraphs whose subsequent lines (all except the first) are uniformly
-    indented by two spaces are considered to be a "tagged paragraphs".  They
-    are unindented accordingly before emission as `.TP` in the [roff] output.
-
-md2man extends [Markdown] semantics in the following ways:
-
-  * The first top-level heading (H1) found in the document is emitted as `.TH`
-    in the roff(7) output to define the UNIX manual page's header and footer.
-    Any subsequent top-level headings (H1) are treated as second-level (H2).
-
 ### For [roff] output
 
 #### At the command line
 
-    md2man --help
+See md2man-roff(1) manual:
+
+    md2man-roff --help
 
 #### Inside a Ruby script
 
 Use the default renderer:
 
-    require 'md2man'
+    require 'md2man/roff/engine'
 
-    your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
+    your_roff_output = Md2Man::Roff::ENGINE.render(your_markdown_input)
 
 Build your own renderer:
 
-    require 'md2man'
+    require 'md2man/roff/engine'
 
-    engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash)
+    engine = Redcarpet::Markdown.new(Md2Man::Roff::Engine, your_options_hash)
     your_roff_output = engine.render(your_markdown_input)
 
 Define your own renderer:
 
-    require 'md2man'
+    require 'md2man/roff/engine'
 
-    class YourManpageRenderer < Md2Man::Engine
+    class YourManpageRenderer < Md2Man::Roff::Engine
       # ... your stuff here ...
     end
 
@@ -102,7 +79,7 @@ Define your own renderer:
 
 Mix-in your own renderer:
 
-    require 'md2man'
+    require 'md2man/roff'
 
     class YourManpageRenderer < Redcarpet::Render::Base
       include Md2Man::Roff
@@ -116,6 +93,8 @@ Mix-in your own renderer:
 
 #### At the command line
 
+See md2man-html(1) manual:
+
     md2man-html --help
 
 #### Inside a Ruby script
@@ -160,6 +139,8 @@ Mix-in your own renderer:
 
 #### At the command line
 
+See md2man-rake(1) manual:
+
     md2man-rake --help
 
 #### Inside a Ruby script

data/VERSION.markdown

@@ -1,3 +1,39 @@
+## Version 2.0.0 (2013-05-05)
+
+This release renames md2man executables and libraries to highlight the fact
+that md2man provides two processing pathways: one for Roff and one for HTML.
+
+Major:
+
+  * Rename md2man(1) executable to md2man-roff(1).
+
+  * Rename `Md2Man::Engine` to `Md2Man::Roff::Engine`.
+
+  * Rename "manpage-reference" CSS class to "md2man-xref" in HTML output.
+
+  * The `Md2Man::Document#reference()` method now takes only two parameters:
+
+    * `input_match` - MatchData object for the reference in Markdown input
+      containing the following named capture groups:
+
+      * `:page` - name of the manual page
+
+      * `:section` - section number of the manual page
+
+    * `output_match` - MatchData object for the reference in output document
+      containing the following named capture groups:
+
+      * `:addendum` - non-space characters immediately after the reference in
+        the output document
+
+Patch:
+
+  * Prevent cross-references from being expanded inside HTML tags.
+
+Other:
+
+  * Add md2man(5) manual page detailing md2man's markdown file format.
+
 ## Version 1.6.2 (2013-05-05)
 
 Patch:

data/bin/md2man-html

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN-HTML 1 2013-05-05 1.6.2
+# MD2MAN-HTML 1 2013-05-05 2.0.0
 
 ## NAME
 
-md2man-html - convert md2man(1) flavored markdown(7) into HTML
+md2man-html - convert md2man(5) flavored markdown(7) into HTML
 
 ## SYNOPSIS
 
@@ -13,22 +13,19 @@ md2man-html - convert md2man(1) flavored markdown(7) into HTML
 
 ## DESCRIPTION
 
-This program converts the markdown(7) input from the given *FILE* into HTML
-and then prints the result to stdout.  stdin is read if *FILE* is not given.
+This program converts md2man(5) flavored markdown(7) input from the given
+*FILE* into HTML 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
+### Cross references
 
-See md2man(1) for details about the document format and Markdown extensions.
-
-### Cross linking
-
-References to other manual pages are converted into hyperlinks that have
-class="manpage-reference" and href="../man${section}/${page}.${section}.html"
+Cross references to manual pages are emitted as HTML hyperlinks that have
+`class="md2man-xref"` and `href="../man$SECTION/$PAGE.$SECTION.html"`
 attributes.
 
-For example, the markdown(7) reference would be converted into HTML as:
+For example, the `printf(3)` cross reference would be emitted as this HTML:
 
-    <a class="manpage-reference" href="../man7/markdown.7.html">markdown(7)</a>
+    <a class="md2man-xref" href="../man3/printf.3.html">printf(3)</a>
 
 ## OPTIONS
 
@@ -37,7 +34,7 @@ For example, the markdown(7) reference would be converted into HTML as:
 
 ## SEE ALSO
 
-md2man(1)
+md2man-roff(1), md2man-rake(1), md2man(5)
 
 =end =========================================================================
 

data/bin/md2man-rake

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# MD2MAN-RAKE 1 2013-05-05 1.6.2
+# MD2MAN-RAKE 1 2013-05-05 2.0.0
 
 ## NAME
 
@@ -42,7 +42,7 @@ Run `rake --help` to see more options.
 
 ## SEE ALSO
 
-rake(1), md2man(1), markdown(7)
+rake(1), md2man-roff(1), md2man-html(1), md2man(5)
 
 =end =========================================================================
 

data/bin/md2man-roff

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# MD2MAN-ROFF 1 2013-05-05 2.0.0
+
+## NAME
+
+md2man-roff - convert md2man(5) flavored markdown(7) into roff(7)
+
+## SYNOPSIS
+
+`md2man-roff` [*OPTION*]... [*FILE*]
+
+## DESCRIPTION
+
+This program converts md2man(5) flavored markdown(7) input from the given
+*FILE* into roff(7) 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.
+
+### Limitations
+
+This program does not convert the following [Redcarpet] nodes into roff(7):
+
+  * `block_html`
+  * `strikethrough`
+  * `superscript`
+  * `image`
+  * `raw_html`
+
+It issues a warning when it encounters these instead.  Patches are welcome!
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+## SEE ALSO
+
+md2man-html(1), md2man-rake(1), md2man(5)
+
+[Redcarpet]: https://github.com/vmg/redcarpet
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+
+require 'md2man/roff/engine'
+puts Md2Man::Roff::ENGINE.render(ARGF.read)

data/lib/md2man/document.rb

@@ -1,5 +1,6 @@
-module Md2Man
-module Document
+require 'md2man'
+
+module Md2Man::Document
 
   #---------------------------------------------------------------------------
   # document-level processing
@@ -18,21 +19,6 @@ module Document
   # block-level processing
   #---------------------------------------------------------------------------
 
-  # This method blocks Redcarpet's default behavior, which cannot be accessed
-  # using super() due to the limitation of how Redcarpet is implemented in C.
-  # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
-  #
-  # You MUST override this method in derived classes and call super() therein:
-  #
-  #   def block_code code, language
-  #     code = super
-  #     # now do something with code
-  #   end
-  #
-  def block_code code, language
-    decode_references code, true
-  end
-
   PARAGRAPH_INDENT = /^\s*$|^  (?=\S)/
 
   # This method blocks Redcarpet's default behavior, which cannot be accessed
@@ -75,23 +61,8 @@ module Document
   # span-level processing
   #---------------------------------------------------------------------------
 
-  # This method blocks Redcarpet's default behavior, which cannot be accessed
-  # using super() due to the limitation of how Redcarpet is implemented in C.
-  # See https://github.com/vmg/redcarpet/issues/51 for the complete details.
-  #
-  # You MUST override this method in derived classes and call super() therein.
-  #
-  #   def codespan code
-  #     code = super
-  #     # now do something with code
-  #   end
-  #
-  def codespan code
-    decode_references code, true
-  end
-
-  def reference page, section, addendum
-    warn "md2man/document: reference not implemented: #{page}(#{section})"
+  def reference input_match, output_match
+    warn "md2man/document: reference not implemented: #{input_match}"
   end
 
 protected
@@ -105,7 +76,7 @@ private
   def encode_references text
     # the [^\n\S] captures all non-newline whitespace
     # basically, it's meant to be \s but excluding \n
-    text.gsub(/([\w\-\.]+)\((\w+)\)(\S*[^\n\S]*)/) do
+    text.gsub(/(?<page>[\w\-\.]+)\((?<section>\w+)\)/) do
       match = $~
       key = encode(match)
       @references[key] = match
@@ -113,13 +84,13 @@ private
     end
   end
 
-  def decode_references text, verbatim=false
-    @references.select do |key, match|
-      replacement = verbatim ? match.to_s : reference(*match.captures)
-      text.sub! key, replacement
-    end.each_key {|key| @references.delete key }
+  def decode_references text
+    @references.delete_if do |key, match|
+      text.sub! /#{Regexp.escape key}(?<addendum>\S*[^\n\S]*)/ do
+        reference match, $~
+      end
+    end
     text
   end
 
 end
-end

data/lib/md2man/html/engine.rb

@@ -1,11 +1,10 @@
 require 'redcarpet'
 require 'md2man/html'
 
-module Md2Man
-module HTML
+module Md2Man::HTML
 
   class Engine < Redcarpet::Render::HTML
-    include HTML
+    include Md2Man::HTML
   end
 
   ENGINE = Redcarpet::Markdown.new(Engine,
@@ -18,4 +17,3 @@ module HTML
   )
 
 end
-end

data/lib/md2man/html.rb

@@ -1,10 +1,9 @@
 require 'cgi'
 require 'md2man/document'
 
-module Md2Man
-module HTML
+module Md2Man::HTML
 
-  include Document
+  include Md2Man::Document
 
   #---------------------------------------------------------------------------
   # block-level processing
@@ -23,10 +22,6 @@ module HTML
     "<dl><dd>#{text}</dd></dl>"
   end
 
-  def block_code code, language
-    "<pre>#{codespan(super)}</pre>"
-  end
-
   def header text, level
     id = text.gsub(/<.+?>/, '-').        # strip all HTML tags
       gsub(/\W+/, '-').gsub(/^-|-$/, '') # fold non-word chars
@@ -37,13 +32,13 @@ module HTML
   # span-level processing
   #---------------------------------------------------------------------------
 
-  def codespan code
-    "<code>#{CGI.escapeHTML(super)}</code>"
-  end
-
-  def reference page, section, addendum
-    url = reference_url(page, section)
-    %{<a class="manpage-reference" href="#{url}">#{page}(#{section})</a>#{addendum}}
+  def reference input_match, output_match
+    if output_match.pre_match =~ /<[^>]*\z/
+      input_match.to_s
+    else
+      url = reference_url(input_match[:page], input_match[:section])
+      %{<a class="md2man-xref" href="#{url}">#{input_match}</a>}
+    end + output_match[:addendum].to_s
   end
 
   # You can override this in a derived class to compute URLs as you like!
@@ -52,4 +47,3 @@ module HTML
   end
 
 end
-end

data/lib/md2man/rakefile/style.css

@@ -1,17 +1,17 @@
 @import url('http://twitter.github.com/bootstrap/assets/css/bootstrap.css');
 
 @media all {
-  .manpage h1,
-  .manpage h2,
-  .manpage h3,
-  .manpage h4,
-  .manpage h5,
-  .manpage h6 {
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
     margin-top: 1em;
   }
 
   /* deactivate external manual page cross-references */
-  a.manpage-reference:not([href]) {
+  a.md2man-xref:not([href]) {
     color: inherit;
     text-decoration: none;
   }
@@ -25,7 +25,7 @@
     margin: auto;
   }
 
-  .manpage > h1:first-child {
+  h1:first-child {
     margin-top: -5em;
     font-weight: normal;
     font-size: smaller;
@@ -34,7 +34,7 @@
 }
 
 @media print {
-  .navbar {
+  .navbar:first-child {
     display: none;
   }
 

data/lib/md2man/rakefile.rb

@@ -30,8 +30,8 @@ task 'md2man:man' => mans
 
 mkds.zip(mans).each do |src, dst|
   render_file_task.call src, dst, lambda {|input|
-    require 'md2man/engine'
-    Md2Man::ENGINE.render(input)
+    require 'md2man/roff/engine'
+    Md2Man::Roff::ENGINE.render(input)
   }
 end
 
@@ -95,7 +95,7 @@ mkds.zip(webs).each do |src, dst|
     require 'md2man/html/engine'
     output = Md2Man::HTML::ENGINE.render(input).
       # deactivate external manual page cross-references
-      gsub(/(?<=<a class="manpage-reference") href="\.\.(.+?)"/) do
+      gsub(/(?<=<a class="md2man-xref") href="\.\.(.+?)"/) do
         $& if webs.include? 'man' + $1
       end
 
@@ -116,9 +116,7 @@ mkds.zip(webs).each do |src, dst|
         '</div>',
       '</div>',
       '<div class="container-fluid">',
-        '<div class="manpage">',
-          output,
-        '</div>',
+        output,
       '</div>',
     ].join
 

data/lib/md2man/{engine.rb → roff/engine.rb}

@@ -1,13 +1,13 @@
 require 'redcarpet'
 require 'md2man/roff'
 
-module Md2Man
+module Md2Man::Roff
+
   class Engine < Redcarpet::Render::Base
-    include Roff
+    include Md2Man::Roff
   end
 
-  ENGINE = Redcarpet::Markdown.new(
-    Md2Man::Engine,
+  ENGINE = Redcarpet::Markdown.new(Engine,
     :tables => true,
     :autolink => true,
     :superscript => true,
@@ -15,4 +15,5 @@ module Md2Man
     :no_intra_emphasis => false,
     :fenced_code_blocks => true
   )
+
 end

data/lib/md2man/roff.rb

@@ -1,9 +1,8 @@
 require 'md2man/document'
 
-module Md2Man
-module Roff
+module Md2Man::Roff
 
-  include Document
+  include Md2Man::Document
 
   #---------------------------------------------------------------------------
   # document-level processing
@@ -43,7 +42,7 @@ module Roff
   end
 
   def block_code code, language
-    code = escape_backslashes(super)
+    code = escape_backslashes(code)
     block_quote "\n.nf\n#{code.chomp}\n.fi\n"
   end
 
@@ -133,8 +132,8 @@ module Roff
   # span-level processing
   #---------------------------------------------------------------------------
 
-  def reference page, section, addendum
-    "\n.BR #{page} (#{section})#{addendum}\n"
+  def reference input_match, output_match
+    "\n.BR #{input_match[:page]} (#{input_match[:section]})#{output_match[:addendum]}\n"
   end
 
   def linebreak
@@ -162,7 +161,7 @@ module Roff
   end
 
   def codespan code
-    code = escape_backslashes(super)
+    code = escape_backslashes(code)
     # NOTE: this double font sequence gives us the best of both worlds:
     # man(1) shows it in bold and `groff -Thtml` shows it in monospace
     "\\fB\\fC#{code}\\fR"
@@ -864,4 +863,3 @@ private
   }
 
 end
-end

data/lib/md2man/version.rb

@@ -1,3 +1,3 @@
 module Md2Man
-  VERSION = "1.6.2"
+  VERSION = "2.0.0"
 end

data/lib/md2man.rb

@@ -1,2 +1 @@
 require 'md2man/version'
-require 'md2man/engine'

data/man/index.html

@@ -2,10 +2,10 @@
 <html>
 <head>
   <meta charset="utf-8" />
-  <meta name="generator" content="md2man 1.6.2 https://github.com/sunaku/md2man" />
+  <meta name="generator" content="md2man 2.0.0 https://github.com/sunaku/md2man" />
   <title>man/index</title>
   <link rel="stylesheet" href="style.css"/>
   <!--[if lt IE 9]><script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script><![endif]-->
 </head>
-<body><div class="container-fluid"><h2 id="man0">man0</h2><dl class="dl-horizontal"><dt><a href="man0/README.html">README</a></dt><dd></dd></dl><dl class="dl-horizontal"><dt><a href="man0/VERSION.html">VERSION</a></dt><dd></dd></dl><h2 id="man1">man1</h2><dl class="dl-horizontal"><dt><a href="man1/md2man-html.1.html">md2man-html(1)</a></dt><dd>convert md2man(1) flavored markdown(7) into HTML</dd></dl><dl class="dl-horizontal"><dt><a href="man1/md2man-rake.1.html">md2man-rake(1)</a></dt><dd>run rake(1) tasks from md2man(1)</dd></dl><dl class="dl-horizontal"><dt><a href="man1/md2man.1.html">md2man(1)</a></dt><dd>convert markdown(7) into roff(7)</dd></dl></div></body>
+<body><div class="container-fluid"><h2 id="man0">man0</h2><dl class="dl-horizontal"><dt><a href="man0/README.html">README</a></dt><dd></dd></dl><dl class="dl-horizontal"><dt><a href="man0/VERSION.html">VERSION</a></dt><dd></dd></dl><h2 id="man1">man1</h2><dl class="dl-horizontal"><dt><a href="man1/md2man-html.1.html">md2man-html(1)</a></dt><dd>convert md2man(5) flavored markdown(7) into HTML</dd></dl><dl class="dl-horizontal"><dt><a href="man1/md2man-rake.1.html">md2man-rake(1)</a></dt><dd>run rake(1) tasks from md2man(1)</dd></dl><dl class="dl-horizontal"><dt><a href="man1/md2man-roff.1.html">md2man-roff(1)</a></dt><dd>convert md2man(5) flavored markdown(7) into roff(7)</dd></dl><h2 id="man5">man5</h2><dl class="dl-horizontal"><dt><a href="man5/md2man.5.html">md2man(5)</a></dt><dd>manual page flavoring for the markdown(7) file format</dd></dl></div></body>
 </html>