kramdown-man 0.1.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 164ce0fc23aa69a61fb65b7c99d26e76a9ab76fc798962f06940412bb1dcbcfd
-  data.tar.gz: 2161ba26365fe958c5a0b5f063706dfe7566d9c1213cb6f84bc63b50dfae4030
+  metadata.gz: 2d53e0152c21c6a0e3e32b4f2dc2d185577eb01f34cd9cbfb8a300e5077e6648
+  data.tar.gz: c825469b0addc74ff69b1d1b53c54021d7020e9ae7284b94913187d58a61e6a9
 SHA512:
-  metadata.gz: 54bd2ea4c4b967a5af505900f6ea8f02edb00900f6e5e6d67d1c015e776e602fe81d1dc641c62f2d7b614fecb224b3cc6003330b38eaa322f80b7296ee96850c
-  data.tar.gz: 28a7d09d3e41e9f108c2a73e966d9ecf31a4343b98b4452c23eab9978b7af77f8ec63a2b870726bb2c39cd0ecd0490fd922ea4e389716c4863fb68fe02dafa3e
+  metadata.gz: fa320fdff23430cb680ad6aadae1b52a79a9eb78bd42ab58b802460c23892f0597a3b536744ffc40584c3309c441a6f8671a37ba9a149653f7ff27ced654f90d
+  data.tar.gz: 69465385b9ec09efcbe01ccb45c014c47dc04485687682167a68dc0f700e3009a34080d0048ffbc3612991fee9dc16f7445dca7078ab52c0c35860ec798a9f89

data/.github/workflows/ruby.yml

@@ -1,10 +1,6 @@
 name: CI
 
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    branches: ['**']
+on: [ push, pull_request ]
 
 jobs:
   tests:
@@ -13,12 +9,11 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.4
-          - 2.5
-          - 2.6
-          - 2.7
           - 3.0
+          - 3.1
+          - 3.2
           - jruby
+          - truffleruby
     name: Ruby ${{ matrix.ruby }}
     steps:
       - uses: actions/checkout@v2

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,64 @@
+### 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
+  file names (ex: `shard.yml`).
+* Use the `.PP` roff macro instead of the deprecated `.HP` macro.
+
 ### 0.1.8 / 2020-12-26
 
 * Upgrade to kramdown 2.x.

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/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013-2020 Hal Brodigan
+Copyright (c) 2013-2023 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,9 +1,12 @@
 # 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)
-* [Email](mailto:postmodern.mod3 at gmail.com)
 
 ## Description
 
@@ -12,123 +15,209 @@ A [Kramdown][kramdown] convert for converting Markdown files into man pages.
 ## 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))` links into man page references.
+  * 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.
 * Uses the pure-Ruby [Kramdown][kramdown] markdown parser.
-* Supports [Ruby] 2.0 and [JRuby].
+* 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'
+```
 
 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
+```
 
 ## Syntax
 
-### Formatting
+### Code
 
-    `code`
+```markdown
+`code`
+```
 
 `code`
 
-    *emphasis*
+### Emphasis
 
+```markdown
 *emphasis*
+```
 
-    **strong**
+*emphasis*
+
+### Strong
+
+```markdown
+**strong**
+```
 
 **strong**
 
-### Paragraphs
+### Paragraph
 
-    Normal paragraph.
+```markdown
+Normal paragraph.
+```
 
 Normal paragraph.
 
-    `command` [`--foo`] *FILE*
+#### Usage String
+
+```markdown
+`command` [`--foo`] **FILE**
+```
 
-`command` [`--foo`] *FILE*
+`command` [`--foo`] **FILE**
 
-    `--tagged`
-      Text here.
+#### Argument Definitions
 
-`--tagged`
-  Text here.
+```markdown
+*ARG*
+: Description here.
+```
+
+*ARG*
+: Description here.
+
+#### Option Definitions
+
+```markdown
+`-o`, `--option` *VALUE*
+: Description 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))
+
+**Note:** only works on [firefox] on Linux.
 
-    Email <bob@example.com>
+[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
+
+```markdown
+ex·am·ple
+: a thing characteristic of its kind or illustrating a general rule.
 
-### Horizontal 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 +225,20 @@ Email <bob@example.com>
 
 ### Code Blocks
 
-        #include <stdio.h>
-    
-        int main()
-        {
-    	    printf("hello world\n");
-    	    return 0;
-        }
+```markdown
+Source code:
+
+    #include <stdio.h>
+
+    int main()
+    {
+        printf("hello world\n");
+        return 0;
+    }
+
+```
+
+Source code:
 
     #include <stdio.h>
 
@@ -158,7 +254,9 @@ Email <bob@example.com>
 
 ## Install
 
-    $ gem install kramdown-man
+```shell
+gem install kramdown-man
+```
 
 ## Alternatives
 
@@ -168,7 +266,7 @@ Email <bob@example.com>
 
 ## Copyright
 
-Copyright (c) 2013-2020 Hal Brodigan
+Copyright (c) 2013-2023 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 
@@ -177,3 +275,4 @@ See {file:LICENSE.txt} for details.
 
 [Ruby]: http://www.ruby-lang.org/
 [JRuby]: http://jruby.org/
+[TruffleRuby]: https://github.com/oracle/truffleruby#readme

data/Rakefile

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 begin
   require 'bundler/setup'

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

@@ -6,6 +6,13 @@ authors: Postmodern
 email: postmodern.mod3@gmail.com
 homepage: https://github.com/postmodern/kramdown-man#readme
 
+metadata:
+  documentation_uri: https://rubydoc.info/gems/kramdown-man
+  source_code_uri:   https://github.com/postmodern/kramdown-man
+  bug_tracker_uri:   https://github.com/postmodern/kramdown-man/issues
+  changelog_uri:     https://github.com/postmodern/kramdown-man/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
 dependencies:
   kramdown: ~> 2.0
 

data/kramdown-man.gemspec

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'yaml'
 
@@ -20,6 +20,7 @@ Gem::Specification.new do |gem|
   gem.authors     = Array(gemspec['authors'])
   gem.email       = gemspec['email']
   gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
 
   glob = lambda { |patterns| gem.files & Dir[*patterns] }