md2man 5.0.1 → 5.0.3

data/man/man5/md2man.5.markdown

@@ -1,8 +1,8 @@
-# MD2MAN 5 2016-02-13 5.0.1
+# MD2MAN 5                        2016-02-21                            5.0.3
 
 ## NAME
 
-md2man - manual page flavoring for the markdown(7) file format
+md2man - UNIX manual page flavoring for the markdown(7) file format
 
 ## DESCRIPTION
 
@@ -11,38 +11,26 @@ pages by extending its syntax, semantics, and assumed processing extensions.
 
 ### Syntax
 
-md2man extends markdown(7) syntax by defining three kinds of paragraphs.
-
-    This is a
-    normal
-    paragraph.
-
-    This is a
-      tagged
-      paragraph.
-
-      This is an
-      indented
-      paragraph.
-
-    This
-     is another
-      normal
-       paragraph.
+md2man extends markdown(7) syntax by distinguishing three kinds of paragraphs.
 
 #### Normal paragraphs
 
 Paragraphs whose lines are all indented by exactly zero or one additional
 spaces are considered to be "normal paragraphs".  For example:
 
-    This is a
-    normal
+    This is a normal paragraph.
+
+    This is also
+    a normal
     paragraph.
 
-    This
-     is another
+    And
+    this
+     is
+     a
       normal
-       paragraph.
+       paragraph
+        too.
 
 #### Tagged paragraphs
 
@@ -70,7 +58,7 @@ md2man extends markdown(7) semantics by treating top-level headings specially.
 #### Top-level headings
 
 The first top-level `<h1>` heading found in the input is considered to be the
-`.TH` directive in roff(7), as described under "Title line" in man-pages(7):
+`.TH` directive in roff(7), described under "Title line" in man-pages(7) thus:
 
 >     .TH title section date source manual
 >
@@ -101,6 +89,99 @@ md2man enables the following [Redcarpet] extensions while reading markdown(7):
   * strikethrough
   * fenced\_code\_blocks
 
+### Examples
+
+Below is a complete example of an md2man(5) formatted manual page adapted from
+the [Linux Man Page Howto](http://www.schweikhardt.net/man_page_howto.html)
+guide by Jens Schweikhardt.  [The result of processing](../man0/EXAMPLE.html)
+this example with md2man-html(1) has been bundled along with this manual page.
+
+```markdown
+FOO 1 "MARCH 1995" Linux "User Manuals"
+=======================================
+
+NAME
+----
+
+foo - frobnicate the bar library
+
+SYNOPSIS
+--------
+
+`foo` [`-bar`] [`-c` *config-file*] *file* ...
+
+DESCRIPTION
+-----------
+
+`foo` frobnicates the bar library by tweaking internal symbol tables. By
+default it parses all baz segments and rearranges them in reverse order by
+time for the xyzzy(1) linker to find them. The symdef entry is then compressed
+using the WBG (Whiz-Bang-Gizmo) algorithm. All files are processed in the
+order specified.
+
+OPTIONS
+-------
+
+`-b`
+  Do not write "busy" to stdout while processing.
+
+`-c` *config-file*
+  Use the alternate system wide *config-file* instead of */etc/foo.conf*. This
+  overrides any `FOOCONF` environment variable.
+
+`-a`
+  In addition to the baz segments, also parse the blurfl headers.
+
+`-r`
+  Recursive mode. Operates as fast as lightning at the expense of a megabyte
+  of virtual memory.
+
+FILES
+-----
+
+*/etc/foo.conf*
+  The system wide configuration file. See foo(5) for further details.
+
+*~/.foorc*
+  Per user configuration file. See foo(5) for further details.
+
+ENVIRONMENT
+-----------
+
+`FOOCONF`
+  If non-null the full pathname for an alternate system wide */etc/foo.conf*.
+  Overridden by the `-c` option.
+
+DIAGNOSTICS
+-----------
+
+The following diagnostics may be issued on stderr:
+
+**Bad magic number.**
+  The input file does not look like an archive file.
+
+**Old style baz segments.**
+  `foo` can only handle new style baz segments. COBOL object libraries are not
+  supported in this version.
+
+BUGS
+----
+
+The command name should have been chosen more carefully to reflect its
+purpose.
+
+AUTHOR
+------
+
+Jens Schweikhardt <howto@schweikhardt.net>
+
+SEE ALSO
+--------
+
+bar(1), foo(5), xyzzy(1), [Linux Man Page Howto](
+http://www.schweikhardt.net/man_page_howto.html)
+```
+
 ## SEE ALSO
 
 markdown(7), man-pages(7), md2man-roff(1), md2man-html(1), md2man-rake(1)

data/man/style.css

@@ -29,9 +29,16 @@
     margin-top: -5em;
     font-weight: normal;
     font-size: smaller;
-    text-align: right;
+    text-align: center;
   }
 
+  h1:first-child > span.md2man-source {
+    float: right;
+  }
+
+  h1:first-child > span.md2man-title,
+  h1:first-child > span.md2man-section,
+  h1:first-child > span.md2man-manual,
   h1:first-child > a.md2man-permalink {
     display: none;
   }

data/test/md2man/html_test.rb

@@ -132,6 +132,57 @@ describe 'html engine' do
     OUTPUT
   end
 
+  it 'decorates top-level headings components in spans with CSS classes' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title section date source manual
+    INPUT
+<h1 id="title-section-date-source-manual"><span class="md2man-title">title</span> <span class="md2man-section">section</span> <span class="md2man-date">date</span> <span class="md2man-source">source</span> <span class="md2man-manual">manual</span><a name="title-section-date-source-manual" href="#title-section-date-source-manual" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# FOO 1 "MARCH 1995" Linux "User Manuals"
+    INPUT
+<h1 id="foo-1-march-1995-linux-user-manuals"><span class="md2man-title">FOO</span> <span class="md2man-section">1</span> <span class="md2man-date">MARCH 1995</span> <span class="md2man-source">Linux</span> <span class="md2man-manual">User Manuals</span><a name="foo-1-march-1995-linux-user-manuals" href="#foo-1-march-1995-linux-user-manuals" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title section date source
+    INPUT
+<h1 id="title-section-date-source"><span class="md2man-title">title</span> <span class="md2man-section">section</span> <span class="md2man-date">date</span> <span class="md2man-source">source</span><a name="title-section-date-source" href="#title-section-date-source" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title section date
+    INPUT
+<h1 id="title-section-date"><span class="md2man-title">title</span> <span class="md2man-section">section</span> <span class="md2man-date">date</span><a name="title-section-date" href="#title-section-date" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title section
+    INPUT
+<h1 id="title-section"><span class="md2man-title">title</span> <span class="md2man-section">section</span><a name="title-section" href="#title-section" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title
+    INPUT
+<h1 id="title"><span class="md2man-title">title</span><a name="title" href="#title" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |#
+    INPUT
+    OUTPUT
+  end
+
+  it 'preserves any extra components found in top-level headings' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |# title section date source manual extra! extra! read all about it!
+    INPUT
+<h1 id="title-section-date-source-manual-extra-extra-read-all-about-it"><span class="md2man-title">title</span> <span class="md2man-section">section</span> <span class="md2man-date">date</span> <span class="md2man-source">source</span> <span class="md2man-manual">manual</span> extra! extra! read all about it!<a name="title-section-date-source-manual-extra-extra-read-all-about-it" href="#title-section-date-source-manual-extra-extra-read-all-about-it" class="md2man-permalink" title="permalink"></a></h1>
+    OUTPUT
+  end
+
   it 'adds permalinks to headings' do
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |# foo *BAR*
@@ -189,4 +240,24 @@ describe 'html engine' do
       |<h3 id="pipes_get_last-chain"><code>PIPES_GET_LAST(CHAIN)</code><a name="pipes_get_last-chain" href="#pipes_get_last-chain" class="md2man-permalink" title="permalink"></a></h3>
     OUTPUT
   end
+
+  it 'supports sole space or tab in codespans' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\s`
+    INPUT
+      |<p><code>\s</code></p>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\t`
+    INPUT
+      |<p><code>\s</code></p>
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\n`
+    INPUT
+      |<p><code>\n</code></p>
+    OUTPUT
+  end
 end

data/test/md2man/roff_test.rb

@@ -17,13 +17,35 @@ describe 'roff engine' do
   SPACE = 0x20.chr
 
   def heredoc document
-    document.gsub(/^\s*\|/, '').chomp
+    document.gsub(/^\s*\|/, '')
   end
 
   it 'renders nothing as nothing' do
     @markdown.render('').must_be_empty
   end
 
+  it 'strips leading newlines' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |
+      |
+      |two leading newlines
+    INPUT
+      |.PP
+      |two leading newlines
+    OUTPUT
+  end
+
+  it 'strips leading newlines but not leading spaces' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |
+      |
+      | two leading newlines followed by one space
+    INPUT
+      |.PP
+      | two leading newlines followed by one space
+    OUTPUT
+  end
+
   it 'renders paragraphs' do
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |just some paragraph
@@ -520,6 +542,39 @@ describe 'roff engine' do
       |.RE
     OUTPUT
 
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |    just some *paragraph*
+      |
+      |     spanning
+      |
+      |
+      |      **multiple**
+      |
+      |    >  lines
+      |    with 4-space indent
+      |
+      |
+      |    and blank lines within
+    INPUT
+      |.PP
+      |.RS
+      |.nf
+      |just some *paragraph*
+      |
+      | spanning
+      |
+      |
+      |  **multiple**
+      |
+      |>  lines
+      |with 4\\-space indent
+      |
+      |
+      |and blank lines within
+      |.fi
+      |.RE
+    OUTPUT
+
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |normal paragraph line
       |
@@ -586,33 +641,47 @@ describe 'roff engine' do
       |Send [me](mailto:foo@bar.baz), e-mail.
     INPUT
       |.PP
-      |Send me
-      |\\[la]foo@bar.baz\\[ra], e\\-mail.
+      |Send me \\[la]foo@bar.baz\\[ra], e\\-mail.
     OUTPUT
 
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |Take [me](http://myself), somewhere.
     INPUT
       |.PP
-      |Take me
-      |\\[la]http://myself\\[ra], somewhere.
+      |Take me \\[la]http://myself\\[ra], somewhere.
     OUTPUT
 
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |Mail me foo@bar.baz now.
     INPUT
       |.PP
-      |Mail me#{SPACE}
-      |\\[la]foo@bar.baz\\[ra] now.
+      |Mail me \\[la]foo@bar.baz\\[ra] now.
     OUTPUT
 
     @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
       |Take me http://www.somewhere now.
     INPUT
       |.PP
-      |Take me#{SPACE}
+      |Take me \\[la]http://www.somewhere\\[ra] now.
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Leave me
+      |http://www.somewhere now.
+    INPUT
+      |.PP
+      |Leave me
       |\\[la]http://www.somewhere\\[ra] now.
     OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |Tagged
+      |  paragraph http://www.should.work correctly.
+    INPUT
+      |.TP
+      |Tagged
+      |paragraph \\[la]http://www.should.work\\[ra] correctly.
+    OUTPUT
   end
 
   it 'renders unordered lists' do
@@ -961,4 +1030,26 @@ describe 'roff engine' do
     OUTPUT
   end
 
+  it 'supports sole space or tab in codespans' do
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\s`
+    INPUT
+      |.PP
+      |\\fB\\fC\s\\fR
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\t`
+    INPUT
+      |.PP
+      |\\fB\\fC\s\\fR
+    OUTPUT
+
+    @markdown.render(heredoc(<<-INPUT)).must_equal(heredoc(<<-OUTPUT))
+      |`\n`
+    INPUT
+      |.PP
+      |\\fB\\fC\n\\fR
+    OUTPUT
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: md2man
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.0.3
 platform: ruby
 authors:
 - Suraj N. Kurapati
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-13 00:00:00.000000000 Z
+date: 2016-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binman
@@ -97,6 +97,8 @@ files:
 - lib/md2man/roff/engine.rb
 - lib/md2man/version.rb
 - man/index.html
+- man/man0/EXAMPLE.html
+- man/man0/EXAMPLE.markdown
 - man/man0/EXAMPLE.png
 - man/man0/README.html
 - man/man0/README.markdown