kramdown-man 0.1.9 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dda435844039b4d61396829d332060c2db27506a3a7eee5d9859e09d9bd49e42
-  data.tar.gz: 46fcc59f2081b7aef517ab9e0e280c4961d370aecca163d78f69a8b3f26298dc
+  metadata.gz: 30fd9e9769c09ef4d6220ce37ee0a810624e996983ab83151f75c35aa573f420
+  data.tar.gz: ab547ca91944b0d38ef7c826a61c69d99a727541793691a2e936595a3c75f039
 SHA512:
-  metadata.gz: d81ca83bdb40321fd8ab52f2c15dc7e94d585641bac442e214a5acb4e9840f2ac38c4e4cb180d6ac03fac6852c3aeacd723988ca93bf837a226912f30cbc2f9e
-  data.tar.gz: 218ca5e6ee857373114abe7d50747cfa89337c0f7a172ee599fbc4e82e60cfb66f12e6ed291dc7d37d904713c0692bde5d8b1fa191d132c1578aa528832de7a8
+  metadata.gz: b2056c28f02cd6ce02a06e21872fa95c22963420ef7e5583f99af92d46767c5d57d23afa187c6587aa1077ee0f6871a54ed6e02e295bba1c7244333c4bbbf451
+  data.tar.gz: 64cb91e4c0c77aed3fca7dedf6d925cd81e35a6ad6b3acd721363b9391a18c8e0460655e88b094bf58b9ed7b85f04eb6f180eb96f89f2d5ca328f515dd2f3c51

data/.gitignore

@@ -1,3 +1,4 @@
-Gemfile.lock
-doc/
-pkg/
+/Gemfile.lock
+/coverage/
+/doc/
+/pkg/

data/.yardopts

@@ -1 +1 @@
---markup markdown --markup-provider kramdown --title "kramdown-man Documentation" --protected
+--markup markdown --title "kramdown-man Documentation" --protected

data/ChangeLog.md

@@ -1,3 +1,69 @@
+### 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.
+* No longer output `.HP` paragraphs due to cross-platform compatibility issues
+  with `groff`, `nroff`, `troff`.
+* Renamed `Kramdown::Converters::Man` to {Kramdown::Man::Converter}.
+* Override {Kramdown::Document#to_man} to use our {Kramdown::Man::Converter}.
+
+#### Syntax
+
+* Added support for definition lists.
+* Switched to using definition lists for documenting options and arguments.
+
+  ```markdown
+  ## ARGUMENTS
+
+  *ARG*
+  : Description goes here.
+
+  ...
+  ```
+
+  ```markdown
+  ## OPTIONS
+
+  `-o`, `--option` *VALUE
+  : Description goes here.
+
+  ...
+  ```
+* Added support for rendering relative links to other markdown man pages
+  as `SEE ALSO` man page references.
+
+  Example:
+
+  ```markdown
+  [foo-bar](foo-bar.1.md)
+  ```
+
+  Will be converted into:
+
+  ```
+  foo-bar(1)
+  ```
+* Ignore horizontal rule elements due to cross-platform compatibility issues
+  with `groff`, `nroff`, `troff`.
+
+#### CLI
+
+* Added the `-o`, `--output FILE` option.
+* Added the `-V`, `--version` option.
+* Display the `kramdown-man.1` man page when `--help` is given, if STDOUT is
+  a TTY. If STDOUT is not a TTY, then the usual `--help` information will be
+  printed.
+
 ### 0.1.9 / 2023-12-01
 
 * Allow markdown `man:file.ext` style links, since man pages can be named after

data/Gemfile

@@ -4,7 +4,10 @@ gemspec
 
 group :development do
   gem 'rake'
-  gem 'rubygems-tasks', '~> 0.2'
-  gem 'rspec', '~> 3.0'
-  gem 'yard', '~> 0.9'
+  gem 'rubygems-tasks',  '~> 0.2'
+  gem 'rspec',           '~> 3.0'
+  gem 'simplecov',      '~> 0.20'
+  gem 'redcarpet',       platform: :mri
+  gem 'yard',            '~> 0.9'
+  gem 'dead_end',        require: false
 end

data/README.md

@@ -1,134 +1,234 @@
 # kramdown-man
 
+[![CI](https://github.com/postmodern/kramdown-man/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/kramdown-man/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/kramdown-man.svg)](https://codeclimate.com/github/postmodern/kramdown-man)
+[![Gem Version](https://badge.fury.io/rb/kramdown-man.svg)](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)
+* [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
 
 * 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.
-* Provides Rake task for converting `man/*.md` into man pages.
+  * Supports converting `[foo-bar](foo-bar.1.md)` and `[bash](man:bash(1))`
+    links into `SEE ALSO` man page references.
+* 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].
 
 ## 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'
+### Rake Task
 
 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
+```
+
+Then you can generate man pages for all `*.md` in the `man/` directory:
+
+```shell
+$ rake man
+```
 
 ## 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**
+```
 
 `command` [`--foo`] **FILE**
 
-    `--tagged`
-      Text here.
+#### Argument Definitions
+
+```markdown
+*ARG*
+: Description here.
+```
+
+*ARG*
+: Description here.
+
+#### Option Definitions
+
+```markdown
+`-o`, `--option` *VALUE*
+: Description here.
+```
 
-`--tagged`
-  Text 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))
+```
 
 [bash](man:bash(1))
 
-    Email <bob@example.com>
+**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
-    
-       extra paragraph
+```markdown
+1. one
+2. two
+3. three
+```
     
 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.
 >
@@ -136,13 +236,15 @@ Email <bob@example.com>
 
 ### Code Blocks
 
-        #include <stdio.h>
-    
-        int main()
-        {
-    	    printf("hello world\n");
-    	    return 0;
-        }
+```markdown
+    #include <stdio.h>
+
+    int main()
+    {
+        printf("hello world\n");
+        return 0;
+    }
+```
 
     #include <stdio.h>
 
@@ -152,17 +254,29 @@ Email <bob@example.com>
 	    return 0;
     }
 
+#### Code Fences
+
+    ```
+    puts "hello world"
+    ```
+
+```
+puts "hello world"
+```
+
 ## 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)
+* [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)
 
@@ -172,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/bin/kramdown-man

@@ -1,16 +1,7 @@
 #!/usr/bin/env ruby
 
-lib_dir = File.expand_path('../lib',File.dirname(__FILE__))
+lib_dir = File.expand_path('../lib',__dir__)
 $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
-require 'kramdown'
-require 'kramdown/man'
-
-case ARGV[0]
-when '-h', '--help'
-  warn "usage: #{File.dirname($0)} <INPUT.md >OUTPUT"
-  exit
-end
-
-doc = Kramdown::Document.new(ARGF.read)
-puts doc.to_man
+require 'kramdown/man/cli'
+exit Kramdown::Man::CLI.run(ARGV)

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/cli.rb

@@ -0,0 +1,202 @@
+require 'kramdown'
+require 'kramdown/man'
+
+require 'optparse'
+
+module Kramdown
+  module Man
+    #
+    # Represents the `kramdown-man` command's logic.
+    #
+    # @api private
+    #
+    # @since 1.0.0
+    #
+    class CLI
+
+      # The program name.
+      PROGRAM_NAME = "kramdown-man"
+
+      # The URL to report bugs to.
+      BUG_REPORT_URL = "https://github.com/postmodern/kramdown-man/issues/new"
+
+      # The path to the man/ directory.
+      MAN_PAGE = File.join(__dir__,'..','..','..','man','kramdown-man.1')
+
+      # The command's option parser.
+      #
+      # @return [OptionParser]
+      attr_reader :option_parser
+
+      # The optional output file to write to.
+      #
+      # @return [String, nil]
+      attr_reader :output
+
+      #
+      # Initializes the command.
+      #
+      def initialize
+        @option_parser = option_parser
+
+        @output = nil
+      end
+
+      #
+      # Initializes and runs the command.
+      #
+      # @param [Array<String>] argv
+      #   Command-line arguments.
+      #
+      # @return [Integer]
+      #   The exit status of the command.
+      #
+      def self.run(argv)
+        new().run(argv)
+      rescue Interrupt
+        # https://tldp.org/LDP/abs/html/exitcodes.html
+        return 130
+      rescue Errno::EPIPE
+        # STDOUT pipe broken
+        return 0
+      end
+
+      #
+      # Runs the command.
+      #
+      # @param [Array<String>] argv
+      #   Command-line arguments.
+      #
+      # @return [Integer]
+      #   The return status code.
+      #
+      def run(argv=ARGV)
+        argv = begin
+                 @option_parser.parse(argv)
+               rescue OptionParser::ParseError => error
+                 print_error(error.message)
+                 return -1
+               end
+
+        markdown = case argv.length
+                   when 1
+                     path = argv[0]
+
+                     unless File.file?(path)
+                       print_error "no such file or directory: #{path}"
+                       return -1
+                     end
+
+                     File.read(path)
+                   when 0
+                     print_error "a MARKDOWN_FILE argument is required"
+                     return -1
+                   else
+                     print_error "too many arguments given"
+                     return -1
+                   end
+
+        doc = Kramdown::Document.new(markdown)
+        man_page = doc.to_man
+
+        if @output
+          File.write(@output,man_page)
+        elsif $stdout.tty?
+          view_man_page(man_page)
+        else
+          puts man_page
+        end
+
+        return 0
+      rescue => error
+        print_backtrace(error)
+        return -1
+      end
+
+      #
+      # Displays the man page using the `man` command.
+      #
+      # @param [String] man_page
+      #   The man page output.
+      #
+      def view_man_page(man_page)
+        io  = IO.popen(%w[man -l -],'w')
+        pid = io.pid
+
+        begin
+          io.puts man_page
+        rescue Errno::EPIPE
+        ensure
+          io.close
+
+          begin
+            Process.waitpid(pid)
+          rescue Errno::EPIPE, Errno::ECHILD
+          end
+        end
+      end
+
+      #
+      # The option parser.
+      #
+      # @return [OptionParser]
+      #
+      def option_parser
+        OptionParser.new do |opts|
+          opts.banner = "usage: #{PROGRAM_NAME} [options] MARKDOWN_FILE"
+
+          opts.on('-o','--output FILE','Write the man page output to the file') do |file|
+            @output = file
+          end
+
+          opts.on('-V','--version','Print the version') do
+            puts "#{PROGRAM_NAME} #{VERSION}"
+            exit
+          end
+
+          opts.on('-h','--help','Print the help output') do
+            if $stdout.tty?
+              system('man',MAN_PAGE)
+            else
+              puts opts
+            end
+
+            exit
+          end
+
+          opts.separator ""
+          opts.separator "Examples:"
+          opts.separator "    #{PROGRAM_NAME} -o man/myprogram.1 man/myprogram.1.md"
+          opts.separator "    #{PROGRAM_NAME} man/myprogram.1.md"
+          opts.separator ""
+        end
+      end
+
+      #
+      # Prints an error message to stderr.
+      #
+      # @param [String] error
+      #   The error message.
+      #
+      def print_error(error)
+        $stderr.puts "#{PROGRAM_NAME}: #{error}"
+      end
+
+      #
+      # Prints a backtrace to stderr.
+      #
+      # @param [Exception] exception
+      #   The exception.
+      #
+      def print_backtrace(exception)
+        $stderr.puts "Oops! Looks like you've found a bug!"
+        $stderr.puts "Please report the following text to: #{BUG_REPORT_URL}"
+        $stderr.puts
+        $stderr.puts "```"
+        $stderr.puts "#{exception.full_message}"
+        $stderr.puts "```"
+      end
+
+    end
+  end
+end