kramdown-man 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d53e0152c21c6a0e3e32b4f2dc2d185577eb01f34cd9cbfb8a300e5077e6648
-  data.tar.gz: c825469b0addc74ff69b1d1b53c54021d7020e9ae7284b94913187d58a61e6a9
+  metadata.gz: 30fd9e9769c09ef4d6220ce37ee0a810624e996983ab83151f75c35aa573f420
+  data.tar.gz: ab547ca91944b0d38ef7c826a61c69d99a727541793691a2e936595a3c75f039
 SHA512:
-  metadata.gz: fa320fdff23430cb680ad6aadae1b52a79a9eb78bd42ab58b802460c23892f0597a3b536744ffc40584c3309c441a6f8671a37ba9a149653f7ff27ced654f90d
-  data.tar.gz: 69465385b9ec09efcbe01ccb45c014c47dc04485687682167a68dc0f700e3009a34080d0048ffbc3612991fee9dc16f7445dca7078ab52c0c35860ec798a9f89
+  metadata.gz: b2056c28f02cd6ce02a06e21872fa95c22963420ef7e5583f99af92d46767c5d57d23afa187c6587aa1077ee0f6871a54ed6e02e295bba1c7244333c4bbbf451
+  data.tar.gz: 64cb91e4c0c77aed3fca7dedf6d925cd81e35a6ad6b3acd721363b9391a18c8e0460655e88b094bf58b9ed7b85f04eb6f180eb96f89f2d5ca328f515dd2f3c51

data/ChangeLog.md

@@ -1,3 +1,14 @@
+### 1.0.1 / 2023-12-05
+
+* Treat markdown code-fence `kd:codespan`s the same as `kd:codeblock`s.
+
+        ```
+        puts "hello world"
+        ```
+  ```
+  puts "hello world"
+  ```
+
 ### 1.0.0 / 2023-12-03
 
 * Ignore `kd:blank` elements to reduce size of generated man pages.

data/README.md

@@ -6,11 +6,12 @@
 
 * [Homepage](https://github.com/postmodern/kramdown-man#readme)
 * [Issues](https://github.com/postmodern/kramdown-man/issues)
-* [Documentation](http://rubydoc.info/gems/kramdown-man/frames)
+* [Documentation](https://rubydoc.info/gems/kramdown-man)
 
 ## Description
 
-A [Kramdown][kramdown] convert for converting Markdown files into man pages.
+Allows you to write man pages for commands in pure Markdown and convert them to
+roff using [Kramdown][kramdown].
 
 ## Features
 
@@ -22,7 +23,9 @@ A [Kramdown][kramdown] convert for converting Markdown files into man pages.
   * Supports multi-paragraph list items and blockquotes.
   * 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.
+* Provides a handy `kramdown-man` command for converting or previewing
+  markdown man pages.
+* Provides a rake task for converting `man/*.md` into man pages.
 * Uses the pure-Ruby [Kramdown][kramdown] markdown parser.
 * Supports [Ruby] 3.x, [JRuby], and [TruffleRuby].
 
@@ -65,6 +68,8 @@ File.write('man/kramdown-man.1',doc.to_man)
 system 'man', 'man/kramdown-man.1'
 ```
 
+### Rake Task
+
 Define a `man` and file tasks which render all `*.md` files within the
 `man/` directory:
 
@@ -73,6 +78,12 @@ require 'kramdown/man/task'
 Kramdown::Man::Task.new
 ```
 
+Then you can generate man pages for all `*.md` in the `man/` directory:
+
+```shell
+$ rake man
+```
+
 ## Syntax
 
 ### Code
@@ -226,8 +237,6 @@ ex·am·ple
 ### Code Blocks
 
 ```markdown
-Source code:
-
     #include <stdio.h>
 
     int main()
@@ -235,11 +244,8 @@ Source code:
         printf("hello world\n");
         return 0;
     }
-
 ```
 
-Source code:
-
     #include <stdio.h>
 
     int main()
@@ -248,6 +254,16 @@ Source code:
 	    return 0;
     }
 
+#### Code Fences
+
+    ```
+    puts "hello world"
+    ```
+
+```
+puts "hello world"
+```
+
 ## Requirements
 
 * [kramdown] ~> 2.0
@@ -260,7 +276,7 @@ gem install kramdown-man
 
 ## Alternatives
 
-* [Redcarpet::Render::ManPage](http://rubydoc.info/gems/redcarpet/Redcarpet/Render/ManPage)
+* [Redcarpet::Render::ManPage](https://rubydoc.info/gems/redcarpet/Redcarpet/Render/ManPage)
 * [ronn](https://github.com/rtomayko/ronn#readme)
 * [md2man](https://github.com/sunaku/md2man#readme)
 
@@ -270,9 +286,9 @@ Copyright (c) 2013-2023 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 
-[kramdown]: http://kramdown.gettalong.org/
-[roff]: http://en.wikipedia.org/wiki/Roff
+[kramdown]: https://kramdown.gettalong.org/
+[roff]: https://en.wikipedia.org/wiki/Roff_(software)
 
-[Ruby]: http://www.ruby-lang.org/
-[JRuby]: http://jruby.org/
+[Ruby]: https://www.ruby-lang.org/
+[JRuby]: https://jruby.org/
 [TruffleRuby]: https://github.com/oracle/truffleruby#readme

data/gemspec.yml

@@ -1,6 +1,9 @@
 name: kramdown-man
-summary: Converts markdown to man pages
-description: A Kramdown converter for converting Markdown files into man pages.
+summary: Allows you to write man pages in pure markdown.
+description: |
+  Allows you to write man pages for commands in pure Markdown and convert them
+  to roff using Kramdown.
+
 license: MIT
 authors: Postmodern
 email: postmodern.mod3@gmail.com

data/lib/kramdown/man/converter.rb

@@ -901,7 +901,22 @@ module Kramdown
       #   The roff output.
       #
       def convert_codespan(codespan)
-        "\\fB#{codespan.value}\\fR"
+        # ``` code fence blocks are parsed as kd:codespans
+        if codespan.options[:codespan_delimiter] == '```'
+          # ignore the first and last newlines
+          contents = escape(codespan.value[1..-2])
+
+          <<~ROFF
+            .PP
+            .RS 4
+            .EX
+            #{contents}
+            .EE
+            .RE
+          ROFF
+        else
+          "\\fB#{escape(codespan.value)}\\fR"
+        end
       end
 
       #

data/lib/kramdown/man/version.rb

@@ -3,6 +3,6 @@
 module Kramdown
   module Man
     # kramdown-man version
-    VERSION = "1.0.0"
+    VERSION = "1.0.1"
   end
 end

data/man/kramdown-man.1

@@ -1,9 +1,12 @@
 .\" Generated by kramdown-man 1.0.0
 .\" https://github.com/postmodern/kramdown-man#readme
 .TH kramdown-man 1 "April 2013" kramdown-man "User Manuals"
+.SH NAME
+.PP
+kramdown\-man \- generates man pages from markdown files
 .SH SYNOPSIS
 .PP
-\fBkramdown-man\fR \[lB]\fIoptions\fP\[rB] \fIMARKDOWN\[ru]FILE\fP
+\fBkramdown\-man\fR \[lB]\fIoptions\fP\[rB] \fIMARKDOWN\[ru]FILE\fP
 .SH DESCRIPTION
 .PP
 A Kramdown
@@ -16,14 +19,14 @@ plugin for converting Markdown files into man pages\.
 The input markdown file to convert\.
 .SH OPTIONS
 .TP
-\fB-o\fR, \fB--output\fR \fIOUTPUT\fP
+\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\.
+\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\.
+\fB\-h\fR, \fB\-\-help\fR
+Prints the usage for \fBkramdown\-man\fR\.
 .SH EXAMPLE
 .PP
 Render a man page from markdown:
@@ -55,8 +58,8 @@ system \(aqman\(aq, \(aqman\[sl]kramdown\-man\.1\(aq
 .RE
 .SS RAKE TASK
 .PP
-Define a \fBman\fR and files tasks which render all \fB*.md\fR files within the
-\fBman/\fR directory:
+Define a \fBman\fR and files tasks which render all \fB*\.md\fR files within the
+\fBman\[sl]\fR directory:
 .PP
 .RS 4
 .EX
@@ -109,7 +112,7 @@ Normal paragraph\.
 .EE
 .RE
 .PP
-\fBcommand\fR \[lB]\fB--foo\fR\[rB] \fBFILE\fP
+\fBcommand\fR \[lB]\fB\-\-foo\fR\[rB] \fBFILE\fP
 .SS Argument Definitions
 .PP
 .RS 4
@@ -130,7 +133,7 @@ Description here\.
 .EE
 .RE
 .TP
-\fB-o\fR, \fB--option\fR \fIVALUE\fP
+\fB\-o\fR, \fB\-\-option\fR \fIVALUE\fP
 Description here\.
 .SS Links
 .PP
@@ -253,8 +256,6 @@ Perfection is achieved, not when there is nothing more to add, but when there is
 .PP
 .RS 4
 .EX
-Source code:
-
     \[sh]include <stdio\.h>
 
     int main()
@@ -262,13 +263,7 @@ Source code:
         printf(\[dq]hello world\en\[dq]);
         return 0;
     \[rC]
-.EE
-.RE
-.PP
-Source code:
-.PP
-.RS 4
-.EX
+
 \[sh]include <stdio\.h>
 
 int main()
@@ -278,6 +273,22 @@ int main()
 \[rC]
 .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
 .PP
 Postmodern 

data/man/kramdown-man.1.md

@@ -1,5 +1,9 @@
 # kramdown-man 1 "April 2013" kramdown-man "User Manuals"
 
+## NAME
+
+kramdown-man - generates man pages from markdown files
+
 ## SYNOPSIS
 
 `kramdown-man` [*options*] *MARKDOWN_FILE*
@@ -175,8 +179,6 @@ ex·am·ple
 
 ### Code Blocks
 
-    Source code:
-
         #include <stdio.h>
 
         int main()
@@ -185,8 +187,6 @@ ex·am·ple
             return 0;
         }
 
-Source code:
-
     #include <stdio.h>
 
     int main()
@@ -195,6 +195,16 @@ Source code:
 	    return 0;
     }
 
+#### Code Fences
+
+    ```
+    puts "hello world"
+    ```
+
+```
+puts "hello world"
+```
+
 ## AUTHOR
 
 Postmodern <postmodern.mod3@gmail.com>

data/spec/cli_spec.rb

@@ -116,6 +116,11 @@ Please report the following text to: #{Regexp.escape(described_class::BUG_REPORT
   let(:markdown_file) { File.join(man_dir,'kramdown-man.1.md') }
 
   describe "#run" do
+    let(:version) { Kramdown::Man::VERSION }
+    let(:man_page_regex) do
+      /\A.\\" Generated by kramdown-man #{Regexp.escape(version)}\n/
+    end
+
     context "when given a markdown file" do
       let(:argv) { [markdown_file] }
 
@@ -129,7 +134,7 @@ Please report the following text to: #{Regexp.escape(described_class::BUG_REPORT
         it "must write the man page output to the output file" do
           subject.run(markdown_file)
 
-          expect(File.read(output)).to match(/\A.\\" Generated by kramdown-man 1.0.0\n/)
+          expect(File.read(output)).to match(man_page_regex)
         end
       end
 
@@ -148,7 +153,7 @@ Please report the following text to: #{Regexp.escape(described_class::BUG_REPORT
         it "must print the man page to stdout" do
           expect {
             subject.run(argv)
-          }.to output(/\A.\\" Generated by kramdown-man 1.0.0\n/).to_stdout
+          }.to output(man_page_regex).to_stdout
         end
       end
 

data/spec/converter_spec.rb

@@ -708,13 +708,37 @@ describe Kramdown::Man::Converter do
   end
 
   describe "#convert_codespan" do
-    let(:code)     { "puts 'hello world'" }
-    let(:markdown) { "`#{code}`" }
+    let(:code)         { "puts 'hello world'" }
+    let(:escaped_code) { 'puts \(aqhello world\(aq' }
+    let(:markdown)     { "`#{code}`" }
 
     let(:codespan) { doc.root.children[0].children[0] }
 
     it "should convert codespan elements into '\\fBcode\\fR'" do
-      expect(subject.convert_codespan(codespan)).to eq("\\fB#{code}\\fR")
+      expect(subject.convert_codespan(codespan)).to eq("\\fB#{escaped_code}\\fR")
+    end
+
+    context "when given a ``` codespan" do
+      let(:markdown) do
+        <<~MARKDOWN
+        ```
+        #{code}
+        ```
+        MARKDOWN
+      end
+
+      it "must treat the codespan element as a codeblock" do
+        expect(subject.convert_codespan(codespan)).to eq(
+          <<~ROFF
+            .PP
+            .RS 4
+            .EX
+            #{escaped_code}
+            .EE
+            .RE
+          ROFF
+        )
+      end
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-man
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-04 00:00:00.000000000 Z
+date: 2023-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -38,7 +38,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: A Kramdown converter for converting Markdown files into man pages.
+description: |
+  Allows you to write man pages for commands in pure Markdown and convert them
+  to roff using Kramdown.
 email: postmodern.mod3@gmail.com
 executables:
 - kramdown-man
@@ -100,5 +102,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Converts markdown to man pages
+summary: Allows you to write man pages in pure markdown.
 test_files: []