Merge pull request #423 from DannyBen/update/manpage-template

Improve manpage template

Author: DannyBen

.rubocop.yml

@@ -28,3 +28,7 @@ RSpec/FilePath:
     - 'spec/bashly/concerns/completions_command_spec.rb'
     - 'spec/bashly/concerns/completions_flag_spec.rb'
 
+# FIXME: This test is ugly and long
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/bashly/integration/rendering_spec.rb'

lib/bashly/extensions/string.rb

@@ -7,6 +7,10 @@ def for_markdown
     gsub('<', '\\<').gsub('>', '\\>').nl2br
   end
 
+  def for_manpage
+    gsub('<', '\\<').gsub('>', '\\>').gsub('`', '**').gsub("\n", "\n\n")
+  end
+
   def nl2br
     gsub("\n", "  \n")
   end
@@ -21,6 +25,10 @@ def to_underscore
     gsub(/(.)([A-Z])/, '\1_\2').gsub(/[- ]/, '_').downcase
   end
 
+  def to_hyphen
+    tr(' ', '-').gsub(/([a-z])([A-Z])/, '\1-\2').downcase
+  end
+
   def to_path
     tr(' ', '/').downcase
   end

lib/bashly/libraries/render/mandoc/mandoc.gtx

@@ -1,9 +1,9 @@
 # Reference: https://linux.die.net/man/5/pandoc_markdown
 
 if version
-> % {{ full_name.tr(' ', '-') }}(1) Version {{ version }} | {{ summary }}
+> % {{ full_name.to_hyphen }}(1) Version {{ version }} | {{ summary }}
 else
-> % {{ full_name.tr(' ', '-') }}(1) | {{ summary }}
+> % {{ full_name.to_hyphen }}(1) | {{ summary }}
 end
 > % {{ ENV['AUTHORS'] }}
 > % {{ Date.today.strftime "%B %Y" }}
@@ -24,7 +24,7 @@ end
 > DESCRIPTION
 > ==================================================
 > 
-> {{ help.for_markdown }}
+> {{ help.for_manpage }}
 >
 
 if default
@@ -42,14 +42,14 @@ if extensible
 end
 >
 
-if commands.any?
+if public_commands.any?
   grouped_commands.each do |group, commands|
     > {{ group.gsub(/:$/, '').upcase }}
     > ==================================================
     >
     commands.each do |subcommand|
       > **{{ subcommand.full_name }}**(1)
-      > :    {{ subcommand.summary.for_markdown }}
+      > :    {{ subcommand.summary.for_manpage }}
       >
     end
     >
@@ -62,7 +62,7 @@ if args.any?
   > 
   args.each do |arg|
     > **{{ arg.name.upcase }}**
-    > :    {{ arg.help.for_markdown }}
+    > :{{ arg.help.for_manpage.indent(4) }}
     >
     if arg.required
       >      - *Required*
@@ -81,7 +81,10 @@ if args.any?
 
   if catch_all.label && catch_all.help
     > **{{ catch_all.label }}**
-    > :    {{ catch_all.help&.for_markdown }}
+    if catch_all.help
+      > :{{ catch_all.help.for_manpage.indent(4) }}
+      >
+    end
     >
 
     if catch_all.required?
@@ -97,7 +100,7 @@ if flags.any?
   > 
   flags.each do |flag|
     > **{{ flag.usage_string }}**
-    > :    {{ flag.help.for_markdown }}
+    > :{{ flag.help.for_manpage.indent(4) }}
     >
 
     if flag.required
@@ -125,8 +128,10 @@ if dependencies.any?
   >
   dependencies.each do |dependency|
     > **{{ dependency.commands.join ', ' }}**
-    >
-    > :{{ dependency.help&.indent(4)&.for_markdown }}
+    if dependency.help
+      > :{{ dependency.help.for_manpage.indent(4) }}
+      >
+    end
     >
   end
 end
@@ -138,7 +143,7 @@ if public_environment_variables.any?
   public_environment_variables.each do |environment_variable|
     > **{{ environment_variable.name.upcase }}**
     >
-    > :{{ environment_variable.help.indent(4).for_markdown }}
+    > :{{ environment_variable.help.for_manpage.indent(4) }}
     >
 
     if environment_variable.required
@@ -157,10 +162,16 @@ if examples
   >
   > ~~~
   examples.each do |example|
-    > {{ example.for_markdown }}
+    > {{ example.for_manpage }}
     >
   end
   > ~~~
 end
 
-
+if public_commands.any?
+  > SEE ALSO
+  > ==================================================
+  >
+  = public_commands.map { |x| "**#{x.full_name.to_hyphen}**(1)" }.join ', '
+  >
+end

lib/bashly/libraries/render/mandoc/render.rb

@@ -11,8 +11,8 @@
   save mdfile, gtx.parse(command)
 
   cmd = %[pandoc -f markdown-smart -s --to man "#{mdfile}" > "#{manfile}"]
-  
-  success = system "#{cmd}"
+
+  success = system cmd
   raise "Failed running pandoc\nMake sure the following command succeeds and try again:\n\n  #{cmd}" unless success
 
   say "g`saved` #{manfile}"

spec/approvals/rendering/mandoc/catch-all-advanced/cli-download.md

@@ -34,6 +34,7 @@ ARGUMENTS
 **AWS PARAMS...**
 :    Additional arguments or flags for AWS CLI
 
+
 OPTIONS
 ==================================================
 

spec/approvals/rendering/mandoc/catch-all-advanced/cli.md

@@ -28,3 +28,8 @@ COMMANDS
 :    Upload a file
 
 
+SEE ALSO
+==================================================
+
+**cli-download**(1), **cli-upload**(1)
+

spec/approvals/rendering/mandoc/dependencies-alt/cli-download.md

@@ -23,13 +23,11 @@ DEPENDENCIES
 
 **git**
 
-:
-
 **ruby**
-
 :    visit $(blue_underlined https://www.ruby-lang.org) to install
 
-**curl, wget**
 
+**curl, wget**
 :    install with $(green sudo apt install curl)
 
+

spec/approvals/rendering/mandoc/dependencies-alt/cli.md

@@ -25,3 +25,8 @@ COMMANDS
 :    Download something
 
 
+SEE ALSO
+==================================================
+
+**cli-download**(1)
+

spec/approvals/rendering/mandoc/docker-like/docker-container.md

@@ -29,3 +29,8 @@ COMMANDS
 :    Stop a container
 
 
+SEE ALSO
+==================================================
+
+**docker-container-run**(1), **docker-container-stop**(1)
+

spec/approvals/rendering/mandoc/docker-like/docker-image.md

@@ -26,3 +26,8 @@ COMMANDS
 :    Show all images
 
 
+SEE ALSO
+==================================================
+
+**docker-image-ls**(1)
+